fithia2/dev/phase6_deliverables/implementation_plan.md

Phase 6 구현 계획

1. 구현 목표

AI 코딩 에이전트는 Phase 6에서 아래 8개의 구현 묶음을 순서대로 완료해야 합니다.

1. 실행 세션/상태 저장 모델 구현
2. broker abstraction 및 reference adapter 구현
3. order planner -> risk guard -> approval gate -> broker submit 흐름 구현
4. canonical order event 저장 및 상태머신 projection 구현
5. reconciliation loop 구현
6. monitoring/alerts/degraded mode 구현
7. dry-run / paper UAT 시나리오 통과
8. live readiness 문서와 gate check 구현

2. 작업 분할

Workstream A — 실행 데이터 모델

• execution_session
• order_intent
• broker_order
• fill_ledger
• position_snapshot
• approval_ticket
• risk_decision
• operator_action

Workstream B — broker adapter

• adapter protocol
• Alpaca paper adapter
• raw event canonicalizer
• adapter error mapping

Workstream C — 실행 코어

• order planner runner
• risk guard service
• approval gate service
• submit/cancel/replace service
• position manager

Workstream D — 상태관리

• event store
• projection builder
• reconciliation worker
• restart recovery flow

Workstream E — 운영

• alerts
• dashboard query layer
• EOD reports
• session control API

3. 권장 구현 순서

Step 1

execution_session, order_intent, broker_order, canonical order event 모델 구현.

Step 2

BrokerAdapter interface와 mock adapter 구현. mock만으로 상태머신 테스트를 먼저 통과시킨다.

Step 3

risk guard와 approval workflow 구현. 브로커 없이도 deny/defer/allow가 잘 동작해야 한다.

Step 4

Alpaca paper adapter 구현. submit/fetch/cancel/stream 최소 경로를 연결한다.

Step 5

state machine projection 및 reconciliation 구현. 재시작 복구 테스트를 먼저 통과시킨다.

Step 6

alerts / degraded mode / no-trade mode 구현.

Step 7

paper UAT 시나리오를 운영 runbook 기준으로 통과시킨다.

Step 8

small-capital live readiness gate만 구현하고, 실제 live enable은 operator explicit flag 없이는 불가하게 둔다.

4. 완료 기준

• mock adapter로 전체 주문 생명주기 테스트가 통과한다.
• Alpaca paper에서 실제 submit/partial fill/cancel 경로가 검증된다.
• reconciliation mismatch를 의도적으로 만들었을 때 탐지 및 해결 루프가 동작한다.
• approval required 모드에서 승인 전 주문 제출이 일어나지 않는다.
• no-trade mode에서 signal 계산은 유지되지만 주문은 전송되지 않는다.
• EOD blotter와 execution journal이 자동 생성된다.

5. 금지사항

• 브로커 SDK raw response를 business logic에 직접 사용하지 말 것.
• 주문 제출과 상태 업데이트를 하나의 giant function에 몰아넣지 말 것.
• restart 이후 내부 메모리 상태를 신뢰해 즉시 신규 주문을 보내지 말 것.
• 예외를 무시하고 다음 루프로 넘어가는 코드 작성 금지.
• approval workflow를 UI 의존적으로 설계하지 말 것. ticket API/DB 기반으로 구현할 것.