# Phase 6 개발문서 패키지

이 문서는 **Phase 0의 전략/리스크/데이터 정책**, **Phase 1의 저장소 구조/DB/서비스 계약**, **Phase 2의 ingestion 파이프라인**, **Phase 3의 parser/feature/label 규칙**, **Phase 4의 백테스터**, **Phase 5의 attention overlay**를 바탕으로,
AI 코딩 에이전트가 **paper trading 및 live execution 운영 레이어**를 구현할 수 있도록 만든 **Phase 6 상세 개발문서**입니다.

## 목표

Phase 6의 목표는 아래 10가지를 실제 코드 수준으로 구현하는 것입니다.

1. **paper trading orchestrator**를 구현한다.
2. **broker abstraction layer**와 최소 1개 브로커(기본 reference: Alpaca paper)를 연동한다.
3. **candidate -> order plan -> order submit -> fill -> position -> exit** 전체 주문 생명주기를 상태머신으로 구현한다.
4. **risk guard / pre-trade checks / kill switch / day halt**를 구현한다.
5. **reconciliation**(브로커 상태와 내부 상태 대사)와 **idempotent recovery**를 구현한다.
6. **human approval mode / fully automatic mode / dry-run mode**를 지원한다.
7. **paper/live 공통 contract**를 정의하고, Phase 4 백테스터 결과와 비교 가능한 blotter를 산출한다.
8. **알림/모니터링/운영 대시보드**를 구현한다.
9. **장애 시 degraded mode / no-trade mode**로 안전하게 전환한다.
10. **실전 운영 전 테스트, paper gate, small-capital live gate**를 문서화한다.

## 포함 문서

- `paper_trading_and_live_architecture.md`
  - Phase 6 전체 아키텍처
  - paper/live 모드 구분
  - 상태 저장과 복구 전략
- `broker_integration_and_order_lifecycle.md`
  - broker abstraction layer
  - 주문/체결/취소/교체 규칙
  - client order id 규칙
- `risk_guard_and_approval_workflow.md`
  - pre-trade / in-trade / post-trade risk guard
  - human approval workflow
  - kill switch / trading halt 정책
- `state_machine_and_reconciliation.md`
  - 실행 상태머신
  - reconciliation loop
  - restart / crash recovery 절차
- `monitoring_alerting_and_ops.md`
  - 운영 모니터링
  - alert routing
  - degraded mode와 no-trade mode
- `configuration_and_schemas.md`
  - live/paper 설정 구조
  - schema 파일 설명
- `implementation_plan.md`
  - AI 코딩 에이전트용 구현 순서
  - 작업 분할
  - 완료 기준
  - 금지사항
- `testing_checklist.md`
  - 단위/통합/replay/failover/UAT 체크리스트
- `operator_runbook.md`
  - 운영자가 장 시작 전/중/후에 수행할 절차
- `live_config.schema.json`
  - Phase 6 런타임 설정 스키마
- `order_event.schema.json`
  - 주문/체결 이벤트 canonical schema
- `approval_ticket.schema.json`
  - human approval ticket schema

## Phase 6 범위

Phase 6에서는 아래를 구현합니다.

- broker abstraction layer
- paper trading runner
- optional live trading runner
- pre-trade checks
- order submit/cancel/replace
- fill handling / partial fill handling
- position lifecycle manager
- reconciliation job
- approval workflow
- kill switch / daily halt / degraded mode
- trade blotter / execution journal / alerts

Phase 6에서는 아직 아래를 구현하지 않습니다.

- multi-broker 동시 생산 운영
- 옵션/선물/숏셀 자동화
- 초단타 ORB 전용 execution stack
- 완전한 웹 기반 OMS/EMS
- 멀티유저 권한 체계
- 24/7 NOC 수준의 운영 자동화

## 핵심 원칙

1. **실행은 항상 보수적이어야 한다.** 좋은 체결보다 잘못된 체결을 피하는 것이 우선이다.
2. **내부 상태와 브로커 상태는 항상 대사 가능해야 한다.**
3. **모든 실행 액션은 재시도 가능해야 하지만, 중복 주문은 절대 허용하지 않는다.**
4. **장애 시에는 자동으로 더 안전한 모드로 degrade 되어야 한다.**
5. **paper와 live는 최대한 같은 코드 경로를 사용한다.**
6. **human approval 없이도 돌아갈 수 있게 설계하되, 초기 운영은 approval mode를 기본으로 한다.**
7. **Phase 0 정책(무료 데이터 전용, 공식 이벤트 우선, 소셜 overlay only)을 절대 깨지 않는다.**

## 권장 구현 순서

1. `paper_trading_and_live_architecture.md`
2. `broker_integration_and_order_lifecycle.md`
3. `state_machine_and_reconciliation.md`
4. `risk_guard_and_approval_workflow.md`
5. `monitoring_alerting_and_ops.md`
6. `configuration_and_schemas.md`
7. `live_config.schema.json`
8. `order_event.schema.json`
9. `approval_ticket.schema.json`
10. `implementation_plan.md`
11. `testing_checklist.md`
12. `operator_runbook.md`

## 완료 기준

Phase 6 완료의 최소 기준은 다음과 같습니다.

- 같은 candidate set으로 dry-run / paper / live-simulated 실행이 같은 order plan을 생성한다.
- broker adapter를 mocking 했을 때 주문/체결/부분체결/취소/교체/거부 전이가 모두 검증된다.
- restart 이후에도 실행 상태를 복구하고 reconciliation이 가능하다.
- approval mode와 auto mode가 동일한 risk checks를 통과한 주문만 제출한다.
- 장중 장애가 발생하면 degraded mode 또는 no-trade mode로 전환할 수 있다.
- 종가 후 trade blotter, exception log, execution journal, risk summary가 생성된다.