fithia2/dev/finished/phase4_deliverables/implementation_plan.md

Implementation Plan

이 문서는 AI 코딩 에이전트가 Phase 4를 실제로 구현할 때의 권장 작업 순서와 완료 기준을 정의합니다.

1. 작업 목표

아래 6개를 끝까지 구현합니다.

1. manifest-driven backtest runner
2. snapshot reader
3. candidate selection / portfolio allocation
4. entry/exit simulation
5. metrics / artifact writer
6. experiment replay / walk-forward support

2. 작업 분할

Task 1. core domain models

구현 대상:

• Candidate
• PlannedOrder
• FilledTrade
• OpenPosition
• DailyPortfolioState
• ExperimentResult
• MetricsBundle

완료 기준:

• domain model 타입이 고정되고 직렬화 가능하다.
• blotter / equity curve / position timeline에 필요한 필드가 모두 있다.

Task 2. market calendar and date alignment

구현 대상:

• trading calendar wrapper
• next trading day lookup
• reaction day / execution day resolver
• timezone utilities

완료 기준:

• 장전/장중/장후 event timestamp를 정확히 trading session으로 매핑한다.
• 휴장일/조기폐장을 안전하게 처리한다.

Task 3. snapshot store

구현 대상:

• feature snapshot loader
• market bar loader
• regime loader
• instrument master loader

완료 기준:

• 특정 run이 같은 snapshot id로 동일 입력을 재현할 수 있다.
• future rows가 로드되지 않는다.

Task 4. candidate selector

구현 대상:

• score threshold filter
• universe filters
• duplicate issuer/event cluster filter
• deterministic sort and tie-break

완료 기준:

• 날짜별 후보 종목이 재현 가능하게 생성된다.
• skip reason이 모두 기록된다.

Task 5. portfolio allocator

구현 대상:

• per-trade risk sizing
• max positions gate
• sector gate
• daily risk budget gate
• cash/exposure updates

완료 기준:

• 같은 입력에서 항상 같은 주문 계획이 나온다.
• 거절 사유가 구조화되어 남는다.

Task 6. execution simulator

구현 대상:

• next-open entry
• stop / target / trailing / time exit
• slippage / commission
• same-bar conservative priority rule

완료 기준:

• 기본 전략 1D/3D/5D 실험이 끝까지 실행된다.
• 체결 규칙이 config 기반으로 바뀔 수 있다.

Task 7. metrics and artifacts

구현 대상:

• trade blotter writer
• daily equity curve writer
• attribution reports
• metrics summary
• plot generation optional

완료 기준:

• run directory가 표준 구조로 생성된다.
• metrics summary JSON이 schema를 만족한다.

Task 8. manifest runner and replay

구현 대상:

• manifest parser
• config merge
• schema validation
• run metadata writer
• replay mode

완료 기준:

• 동일 manifest 재실행 시 동일 결과가 나온다.

3. 권장 구현 순서

1. domain models
2. calendar/date alignment
3. snapshot store
4. candidate selector
5. portfolio allocator
6. execution simulator
7. metrics writer
8. manifest runner
9. walk-forward and split helpers
10. optional plots

4. 구현 규칙

• 순수 함수 중심으로 작성
• hidden global state 금지
• timezone naive datetime 금지
• tie-break 랜덤화 금지
• silent coercion 금지
• future data fallback 금지

5. 최소 디렉터리 제안

apps/backtester/
  run.py
  replay.py
libs/backtest/
  domain.py
  calendar.py
  snapshot_store.py
  selector.py
  allocator.py
  execution.py
  metrics.py
  artifacts.py
  manifests.py
  splits.py
tests/
  unit/backtest/
  integration/backtest/
  replay/

6. 금지사항

• 결과를 좋게 보이게 하기 위한 parameter auto-tuning 루프를 기본 구현에 넣지 말 것
• 평가 지표 계산 전에 손실 거래를 필터링하지 말 것
• missing data를 0으로 임의 대체하지 말 것
• event timestamp가 없는데 filing date로 임의 대체한 뒤 경고를 남기지 않는 것 금지
• 같은 바에서 stop/target 순서를 유리하게 처리하는 것 금지

7. 완료 정의

다음이 모두 충족되면 Phase 4 구현 완료로 봅니다.

• baseline experiment manifest를 한 번 실행할 수 있다.
• 결과 디렉터리에 metrics, blotter, equity curve가 생성된다.
• regression snapshot으로 결과가 고정된다.
• year split, regime split, ablation run을 각각 최소 1개씩 실행할 수 있다.
• testing checklist의 P0 항목이 모두 통과한다.