# Phase 4 개발문서 패키지

이 문서는 **Phase 0의 전략/리스크/데이터 정책**, **Phase 1의 저장소 구조/DB/서비스 계약**, **Phase 2의 ingestion 파이프라인**, **Phase 3의 parser/feature/label 규칙**을 바탕으로,
AI 코딩 에이전트가 **누수 없는 event-driven 백테스터와 실험/평가 체계**를 구현할 수 있도록 만든 **Phase 4 상세 개발문서**입니다.

## 목표

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

1. **event-driven backtest engine**을 구현한다.
2. **reaction day / entry day / holding horizon**을 정확히 처리한다.
3. **look-ahead bias / survivorship bias / timestamp leakage**를 방지한다.
4. **포트폴리오/리스크/자금 배분 규칙**을 백테스트에 반영한다.
5. **point-in-time feature snapshot**만으로 시뮬레이션한다.
6. **실험 정의(manifest), 결과 저장, 재현 가능한 실행 규칙**을 만든다.
7. **평가 지표와 리포트 산출물**을 고정한다.
8. **ablation / walk-forward / regime split** 실험 체계를 만든다.
9. **Phase 6 paper trading과 비교 가능한 output contract**를 만든다.

## 포함 문서

- `backtest_architecture.md`
  - Phase 4 전체 아키텍처
  - 입력/출력 데이터 계약
  - engine 경계와 상태 전이
- `simulation_engine_design.md`
  - 백테스터 내부 동작 상세
  - event queue / calendar / fill logic / price lookup 규칙
- `portfolio_and_risk_model.md`
  - 포지션 sizing
  - 동시보유 수
  - 섹터 집중 제한
  - 손절/익절/시간청산 모델
- `experiment_and_evaluation_plan.md`
  - 실험 정의 방식
  - evaluation metrics
  - ablation / walk-forward / split 규칙
- `configuration_and_schemas.md`
  - config 파일 구조
  - manifest 사용 규칙
  - 결과 저장 포맷
- `implementation_plan.md`
  - AI 코딩 에이전트용 구현 순서
  - 작업 분할
  - 완료 기준
  - 금지사항
- `testing_checklist.md`
  - 단위/통합/replay/통계/운영 전 테스트 체크리스트
- `operator_research_runbook.md`
  - 연구자가 백테스트를 실행하고 결과를 검증하는 절차
- `backtest_config.schema.json`
  - 백테스트 설정 JSON Schema
- `experiment_manifest.schema.json`
  - 실험 실행 manifest JSON Schema

## Phase 4 범위

Phase 4에서는 아래까지만 구현합니다.

- event-driven 백테스터
- point-in-time feature snapshot reader
- signal ranking / candidate selection
- portfolio / risk / sizing engine
- execution approximation (next open / close / stop / trailing / time exit)
- evaluation / report writer
- experiment registry / manifest runner
- walk-forward / split utilities

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

- 실시간 주문 전송
- broker API live execution
- paper trading orchestration
- human approval workflow
- 실전 알림/모니터링

## 핵심 원칙

1. **백테스트는 live가 나중에 따라와야 할 기준이 아니라, live와 같은 제약을 최대한 먼저 반영하는 장치**여야 한다.
2. **미래 정보는 단 1바이트도 사용하지 않는다.**
3. **event timestamp와 market session 경계를 정확히 처리한다.**
4. **문서/피처/라벨이 생성된 시각을 명시적으로 관리한다.**
5. **모든 실험은 manifest 기반으로 재현 가능해야 한다.**
6. **좋아 보이는 결과보다, 설명 가능한 결과를 우선한다.**
7. **Phase 0 정책(무료 데이터 전용, 공식 이벤트 우선, 소셜 overlay only)을 절대 깨지 않는다.**

## 권장 구현 순서

1. `backtest_architecture.md`
2. `simulation_engine_design.md`
3. `portfolio_and_risk_model.md`
4. `configuration_and_schemas.md`
5. `backtest_config.schema.json`
6. `experiment_manifest.schema.json`
7. `implementation_plan.md`
8. `testing_checklist.md`

## 완료 기준

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

- 1D / 3D / 5D horizon 전략을 같은 엔진에서 재현 가능하게 실행할 수 있다.
- event timestamp와 session alignment가 테스트로 검증되어 있다.
- candidate ranking → position sizing → fills → exits → metrics pipeline이 끝까지 동작한다.
- 하나의 manifest로 동일 실험을 다시 실행했을 때 같은 결과가 나온다.
- Phase 5 attention overlay 전/후 ablation이 비교 가능하다.
- 실험 리포트에 주요 KPI와 trade blotter, attribution, failure cases가 포함된다.