# 하이브리드 자동매매 멀티스레드 아키텍처

업비트 20여 종목·가변 분봉·실시간 손절/익절을 위한 **이벤트 기반 비동기 파이프라인** 설계 및 구현 요약.

## 1. 시스템 레이어

| 레이어 | 구현 클래스 | 역할 |
|--------|-------------|------|
| **Ingestion** | `UpbitWebSocketClient` | WS 수신·파싱만 수행 → `TradeEventQueue.offer()` |
| **Event Buffer** | `TradeEventQueue` | `LinkedBlockingQueue` (기본 65536) |
| **Core Engine** | `CoreEngineWorkerPool` + `MarketTickProcessor` | 고정 워커 풀(기본 6) → 캔들·SL/TP |
| **Execution** | `OrderExecutionQueue` | 단일 쓰레드 + Guava `RateLimiter` (기본 5/s) |

## 2. 가변 분봉

- `BarBuilder`: 체결 틱 → 1m 조립 → 3m/5m/15m/30m/1h/4h/1d 전파
- **봉 마감 시** `evaluateStrategyOnBarClose()` — 1m 및 상위 TF 마감마다 ta4j 전략 평가
- `CANDLE_CLOSE` / `REALTIME_TICK` 실행 방식 유지

## 3. 실시간 손절/익절 (이원화)

| 경로 | 트리거 | 클래스 |
|------|--------|--------|
| 진입/청산 (전략) | 봉 마감 | `BarBuilder` → `OrderExecutionQueue` |
| 손절/익절 | 매 틱 | `RealtimePositionMonitor` → `OrderExecutionQueue` |

- SL/TP 비율: **백테스트 설정** (`GcBacktestSettings` / API) 재사용
- 모의투자 ON + 보유 포지션일 때만 동작

## 4. 장애 대응

| 기능 | 클래스 | 설정 |
|------|--------|------|
| WS 재연결 | `UpbitWebSocketClient` + `WebSocketStalenessMonitor` | `stale-tick-seconds: 30` |
| 갭 백필 | `CandleGapBackfillService` | cron `0 */5 * * * *`, REST 20봉 |
| 메모리 상한 | `Ta4jStorage` | 파이프라인 ON 시 `max-bars-per-series: 500` |

## 5. 설정 (`application.yml`)

```yaml
goldenchart:
  trading:
    pipeline:
      enabled: true
      queue-capacity: 65536
      worker-threads: 6
      order-rate-per-second: 5.0
      max-bars-per-series: 500
      stale-tick-seconds: 30
      gap-backfill-cron: "0 */5 * * * *"
      gap-backfill-candle-count: 20
```

`enabled: false` 시 기존 동기 경로(WS → `BarBuilder.onTick` 직접)로 폴백.

## 6. 모니터링 API

| 엔드포인트 | 용도 |
|------------|------|
| `GET /api/trading/pipeline/status` | 파이프라인 전체 스냅샷 (프로세스·JVM·트래픽·스레드) |
| `GET /api/dashboard/summary` | 운영 대시보드 (`systemMonitor` 필드에 동일 스냅샷 포함) |

**systemMonitor** 주요 항목: `processes`(레이어별 상태), `jvm`(Heap·스레드), `traffic`(초당 틱/WS/주문), `memory`(Ta4j), `queue`/`workers`/`orders`, `threads`, `staleMarkets`.

## 7. 패키지

`com.goldenchart.trading.pipeline.*`