# 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. 최소 디렉터리 제안

```text
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 항목이 모두 통과한다.