# Phase 6 아키텍처 — Paper Trading & Live Execution

## 1. 목적

Phase 6의 목적은 Phase 4의 백테스트 신호와 Phase 5의 overlay 결과를 **실제 주문 가능한 execution plan**으로 변환하고,
이를 **paper trading**에서 충분히 검증한 뒤 **small-capital live execution**으로 이행할 수 있는 운영 레이어를 구현하는 것입니다.

핵심은 다음과 같습니다.

- 전략 신호 생성과 주문 실행을 분리한다.
- 실행 시스템은 신호를 맹신하지 않고 별도의 risk guard를 통과한 주문만 보낸다.
- paper/live의 코드 경로를 최대한 동일하게 유지한다.
- 실행 실패, 네트워크 장애, 브로커 지연, 부분체결, 재시작을 모두 가정한다.

## 2. 상위 구성

```text
signal pipeline (Phase 2~5)
  -> candidate store
  -> order planner
  -> risk guard
  -> approval gate (optional)
  -> broker adapter
  -> execution event bus
  -> position manager
  -> reconciliation loop
  -> alerts / blotter / dashboard
```

### 2.1 구성 요소

#### candidate reader
- Phase 4/5 산출물에서 실행 가능한 후보를 읽는다.
- 후보는 `trade_date`, `symbol`, `side`, `entry_window`, `planned_stop`, `planned_time_exit`, `score`, `portfolio_bucket`을 가져야 한다.

#### order planner
- 후보를 실제 주문 단위로 변환한다.
- sizing 결과, 주문 타입, limit/stop 가격, TTL, submission window를 계산한다.
- planner는 브로커 API를 직접 호출하지 않는다.

#### risk guard
- 계좌 기준, 종목 기준, 전략 기준, 운영 기준 제한을 체크한다.
- pre-trade 단계에서만 끝나지 않고 in-trade/post-trade 검사도 포함한다.

#### approval gate
- human-in-the-loop가 필요한 초기 운영 모드용 모듈이다.
- 승인/거절/수정 요청을 ticket 기반으로 기록한다.

#### broker adapter
- 최소 인터페이스만 노출한다.
- submit, cancel, replace, fetch order, fetch positions, fetch fills, heartbeat.
- Phase 6의 기본 reference broker는 Alpaca paper이다. live 지원은 adapter 수준에서 optional로 둔다.

#### execution event bus
- 주문 제출 결과, 체결, 취소, 거부, 연결 장애, 재동기화 이벤트를 canonical event로 변환한다.
- 내부 상태머신은 브로커별 raw payload가 아니라 canonical event를 소비한다.

#### position manager
- 실행 포지션, 평균단가, 남은 수량, stop 상태, time exit 상태를 관리한다.
- 백테스터와 동일한 청산 규칙을 실전용으로 근사 적용한다.

#### reconciliation loop
- 주기적으로 브로커 상태와 내부 상태를 비교한다.
- 누락 이벤트, 중복 체결, orphan order, stale position을 탐지한다.

## 3. 실행 모드

### 3.1 dry-run mode
- 주문을 브로커에 보내지 않는다.
- order plan과 risk decision만 생성한다.
- 모든 알림/로그/리포트는 동일하게 생성한다.
- Phase 6 초반 개발 단계의 기본 모드다.

### 3.2 paper mode
- broker paper endpoint에만 주문을 보낸다.
- 체결과 취소 이벤트를 실시간으로 소비한다.
- 운영 프로세스 검증과 상태머신 검증용이다.

### 3.3 live mode
- 실제 주문을 보낸다.
- 기본은 human approval required.
- auto mode는 충분한 paper 성과와 운영 안정성 확인 후에만 허용한다.

## 4. 세션 기준 실행 타임라인

### T-1 (전일 종가 후)
- 최종 candidate snapshot 확정
- overlay score 반영 완료
- order plan preview 생성
- 리스크 및 자금 사용 가능성 점검

### T (장 시작 전)
- broker/account health check
- market calendar / holiday / half-day 확인
- latest candidate consistency check
- approval mode일 경우 주문 티켓 생성

### T (장중)
- entry window 도달 시 주문 제출
- fill / partial fill / reject / cancel 이벤트 처리
- intraday risk guard 점검
- 일일 손실 또는 시스템 장애 발생 시 신규 주문 중단

### T (장 종료 직전/후)
- time exit 대상 주문 처리
- 종가 기반 상태 업데이트
- blotter / execution summary / reconciliation 수행

## 5. 상태 저장 원칙

상태는 메모리에만 두지 않는다. 아래는 반드시 durable storage에 기록한다.

- candidate snapshot id
- order plan id
- approval ticket
- client_order_id
- broker_order_id
- canonical order event
- position snapshot
- exception / operator action

## 6. 공통 코드 경로 원칙

아래 모듈은 dry-run / paper / live에서 공통 코드 경로를 사용해야 한다.

- candidate selection input reader
- order planner
- risk guard
- state machine
- blotter generator
- reconciliation core logic

브로커 endpoint 차이는 broker adapter와 credential/config 계층에서만 나뉘어야 한다.

## 7. Phase 4와 연결되는 contract

Phase 4에서 생성한 backtest candidate와 Phase 6에서 실행하는 candidate는 최소한 다음 필드를 공유해야 한다.

- `candidate_id`
- `symbol`
- `side`
- `strategy_id`
- `event_id`
- `trade_date`
- `entry_policy`
- `planned_stop_policy`
- `planned_time_exit_policy`
- `score_total`
- `score_components`
- `sizing_inputs`

Phase 6는 이 contract를 받아 live-specific 필드를 추가한다.

- `execution_session_id`
- `broker_name`
- `broker_account_id`
- `client_order_id`
- `approval_ticket_id`
- `risk_decision`

## 8. 실패에 대비한 설계

Phase 6는 반드시 아래 실패를 정상 흐름으로 가정해야 한다.

- broker websocket disconnect
- HTTP timeout
- duplicate callback
- order accepted 후 fill event 지연
- cancel requested 후 already filled
- replace requested 후 partial fill 선행
- process restart 중 이벤트 손실
- operator가 수동으로 브로커 화면에서 주문을 변경한 경우

이 실패들에 대한 대응은 `state_machine_and_reconciliation.md`에서 구체화한다.