# Milestone: Backtest Multi-Timeframe Coverage

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/backtest-loop/PHASE.md`

## 목표

월봉, 일봉, 분봉을 ALT 백테스트의 기본 분석 timeframe으로 정리한다. 현재 일봉 중심으로 닫힌 data import/store/backtest/headless smoke를 multi-timeframe 기준으로 확장하고, 지원하지 않는 provider/timeframe 조합은 조용히 실패하지 않고 명시적으로 거부하거나 대체 생성 경로를 남긴다.

## 상태

[계획]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: `agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md`
- SDD 사유: timeframe contract/proto, provider capability, DB 저장 key, aggregation provenance, backtest fill policy와 field smoke가 함께 바뀐다.
- 잠금 해제 조건: 아래 체크리스트
  - [x] SDD 잠금이 해제되어 있다.
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
  - [x] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다.
- 결정 필요: 없음
- 결정 반영:
  - D01: 분봉 1차 import/backtest 검증 baseline은 `1m`/`5m`를 함께 포함한다.
  - D02: 월봉 source of truth는 provider 월봉과 병행하지 않고 일봉 기반 deterministic aggregation 하나로 둔다.

## 범위

- contracts/proto, Go domain, CLI scenario vocabulary에서 월봉, 일봉, 분봉 timeframe을 백테스트 기본 분석 단위로 정리
- provider capability matrix가 timeframe별 지원 여부와 거부 사유를 표현하도록 보강
- 분봉 provider import 또는 명시적 미지원 거부 경계
- 월봉 일봉 기반 deterministic aggregation 경계와 provenance 기록
- `bars` 저장/조회, freshness/gap/duplicate/readiness 확인이 월/일/분 timeframe을 구분해 동작하도록 검증
- backtest run selector, engine input, result handoff가 월/일/분봉 시나리오를 headless로 검증할 수 있게 하는 흐름

## 기능

### Epic: [timeframe-contract] Timeframe contract

월봉, 일봉, 분봉을 사용자 입력, contracts, domain, CLI output에서 같은 의미로 다루게 한다.

- [ ] [timeframe-vocab] proto/domain/CLI scenario에 monthly/daily/minute timeframe vocabulary를 정리하고 기존 `daily`, `minute_1`, `minute_5` 매핑과 호환성을 유지한다. 검증: contracts/domain/CLI mapping test가 monthly와 minute baseline을 포함한다.
- [ ] [capability-matrix] provider, market, venue, asset type, timeframe별 지원/미지원 사유를 capability matrix로 표현한다. 검증: KIS KR/US daily, minute, monthly 조합의 accepted/rejected case가 명시적으로 통과한다.

### Epic: [data-coverage] Multi-timeframe data coverage

백테스트 입력 데이터가 월/일/분 timeframe별로 수집 또는 생성되고 저장될 수 있게 한다.

- [ ] [minute-ingest] 분봉 provider import 경계를 추가하거나, provider 미지원 조합을 typed error로 거부한다. 검증: minute import success 또는 rejected fixture가 stable text/JSONL로 남는다.
- [ ] [monthly-bars] 월봉을 일봉 aggregation으로 생성하고, 생성 기준과 provenance를 저장/출력한다. 검증: 동일 daily fixture에서 deterministic monthly OHLCV가 생성된다.
- [ ] [store-query] `bars` 저장/조회와 backtest bar source가 timeframe별 key를 유지하고 월/일/분 데이터를 섞지 않는다. 검증: 동일 instrument의 monthly/daily/minute bars가 독립 조회된다.

### Epic: [backtest-semantics] Backtest semantics

전략 실행과 결과 handoff가 timeframe 차이를 명시적으로 다룬다.

- [ ] [run-selector] backtest scenario matrix가 monthly/daily/minute timeframe을 표현하고 각 timeframe의 입력 기간을 검증한다. 검증: matrix expand test와 dry-run validation이 monthly/daily/minute run id를 생성한다.
- [ ] [fill-policy] daily 전용 fill policy를 multi-timeframe 용어로 재정리하고, timeframe별 체결/next-bar 규칙을 명시한다. 검증: fixture backtest가 monthly/daily/minute 각각 deterministic result를 낸다.
- [ ] [freshness-readiness] collection freshness와 readiness output이 월/일/분 timeframe별 latest/missing/gap/duplicate 상태를 구분한다. 검증: monthly/daily/minute freshness fixture가 stable text/JSONL로 구분된다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- multi-timeframe 전략 DSL 또는 고급 factor language 전체
- tick data, order book, 실시간 streaming bar construction
- Flutter 운영 화면 구현
- 실거래 order routing 또는 broker execution 변경
- 외부 provider credential 값이나 개인 secret 문서화

## 작업 컨텍스트

- 관련 경로: `packages/contracts/proto/alt/v1/`, `packages/domain/market/`, `packages/domain/backtest/`, `services/worker/`, `services/api/`, `apps/cli/`, `agent-test/local/`
- 표준선(선택): 일봉 MVP는 이미 완료된 기준선이며, multi-timeframe은 기존 일봉 경로를 깨지 않고 additive하게 확장한다.
- 표준선(선택): provider가 직접 제공하지 않는 timeframe은 deterministic aggregation 또는 명시적 typed rejection 중 하나를 선택해 조용한 fallback을 피한다.
- 표준선(선택): 백테스트는 먼저 단일 timeframe run을 확실히 닫고, 여러 timeframe을 동시에 참조하는 전략은 후속 Milestone으로 미룬다.
- 선행 작업: Backtest Data Collection Infrastructure, Backtest Scenario Automation
- 후속 작업: Scheduled Market Data Refresh의 multi-timeframe cadence 보강, Multi-Timeframe Strategy Composition 후보
- 결정: 분봉 1차 import/backtest 검증 baseline은 `1m`/`5m`를 함께 포함하고, 월봉 source of truth는 일봉 기반 deterministic aggregation 하나로 둔다.