fithia2/dev/phase6_deliverables/paper_trading_and_live_architecture.md

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. 상위 구성

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에서 구체화한다.