# Milestone: Backtest Data Collection Infrastructure

## 위치

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

## 목표

사용자가 정한 종목군을 대상으로 자동 수집과 일별 갱신을 수행하고, 백테스트에 필요한 정제 데이터만 DB에 남기는 headless 인프라를 만든다. 이 마일스톤은 에이전트 도입이 아니라 백테스팅을 실제로 반복하기 위한 데이터 준비, freshness 확인, 실행 입력 안정화에 집중한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- 사용자가 정한 종목군/watchlist를 수집 대상으로 삼는 설정 경계
- 가능한 넓은 provider/data 접근을 수용할 수 있는 수집 adapter 경계
- 매일 갱신 가능한 collection job과 실패/누락 재시도 흐름
- 백테스트에 필요한 정제 데이터만 DB에 남기는 persistence 기준
- headless CLI/log/YAML 또는 동등한 운영 경로에서 freshness와 readiness를 확인하는 표면
- 저장된 데이터에서 재현 가능한 backtest input range를 선택하는 준비 경계

## 기능

### Epic: [universe] Selected universe collection

사용자가 지정한 종목군을 수집 대상으로 삼고, 매일 반복 가능한 수집 단위로 관리한다.

- [x] [watchlist-config] 선택 종목군을 수집 대상으로 등록하고 갱신할 수 있는 headless 설정 경계를 만든다.
- [x] [daily-collect] 선택 종목군에 대해 일별 수집 job을 실행하고 재실행할 수 있는 worker/CLI 경계를 만든다.
- [x] [freshness-status] 수집 성공, 실패, 누락, 최신 일자를 operator가 확인할 수 있는 상태 출력을 만든다.

### Epic: [dataset] Backtest-ready dataset

수집한 원천 데이터를 백테스트 입력으로 사용할 수 있는 정제 데이터로 저장한다.
작업 운영 기준: 문서, fixture, test, 단일 모듈 정합성 보강처럼 작고 되돌리기 쉬운 작업은 바로 작업한다. DB schema, persistence contract, provider adapter, API/worker 경계처럼 여러 모듈과 데이터 계약을 바꾸는 큰 작업은 먼저 plan을 작성한다.

- [x] [provider-boundary] KIS/KRX/DART/US provider 등 확장 가능한 data source adapter 경계를 정리한다.
- [x] [normalized-store] 백테스트에 필요한 정제 필드만 DB에 저장하고 원천 payload 전체 저장은 기본값에서 제외한다.
- [x] [gap-handling] 결측, 휴장일, 중복, provider 지연을 백테스트 입력에서 식별할 수 있게 한다.

### Epic: [backtest-ready] Repeatable execution input

정제 데이터가 실제 백테스트 실행 입력으로 반복 사용될 수 있게 연결한다.

- [x] [input-selector] 저장된 정제 데이터에서 종목군, 기간, frequency를 선택해 backtest run input으로 넘기는 경계를 만든다.
- [x] [headless-smoke] 샘플 종목군 수집부터 기본 backtest 실행까지 headless smoke로 검증한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-15
- 완료 근거: `watchlist-config`, `daily-collect`, `freshness-status`, `provider-boundary`, `normalized-store`, `gap-handling`, `headless-smoke`, `input-selector` 기능 Task가 모두 충족되었다. `input-selector`는 `01_input_selector_contract`, `02+01_storage_bar_selector`, `03+01,02_backtest_selector_flow` split 완료로 저장 데이터 selector부터 backtest run input 연결까지 충족되었다. 2026-06-15 코드레벨 검토 중 `start_backtest` dry-run market 검증 공백을 작게 보강했고, 전체 테스트/lint/build가 통과했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 요청에 따라 2026-06-15 완료 처리 및 archive 이동을 수행했다.

## 범위 제외

- 에이전트 도입, 에이전트 skill 설계, agent runtime 연결
- 주식 분석/전략 판단 로직 자체의 설계
- Flutter 운영 화면 구현
- paper/live order routing과 실거래 execution
- 외부 provider credential 값이나 개인 secret 문서화

## 작업 컨텍스트

- 관련 경로: `services/worker/`, `apps/cli/`, `packages/domain/`, `packages/contracts/`, `deployments/local/`
- 표준선(선택): 백테스트 인프라는 먼저 화면 없이 CLI, terminal output, YAML scenario, log, test fixture로 검증한다.
- 표준선(선택): 데이터 접근 범위는 좁히지 않고 확장 가능한 adapter 경계로 열어두되, DB에는 백테스트와 운영 판단에 필요한 정제 데이터만 남긴다.
- 표준선(선택): agent는 이 마일스톤의 구현 수단이나 주식 분석 코어가 아니다.
- 완료 근거(watchlist-config): CLI scenario schema에 top-level named universe 설정과 `request.universe` 참조가 추가되었고, KR/US/smoke market data fixtures가 inline watchlist 대신 named universe를 사용한다. 2026-06-14에 `go test ./apps/cli/internal/operator ./apps/cli/internal/cli`가 통과했다. 증거: `agent-task/archive/2026/06/m-backtest-data-collection-infrastructure/01_watchlist_config/complete.log`.
- 완료 근거(daily-collect): `import_daily_bars`가 API -> worker -> importer로 전달되고 CLI scenario에서 실행/재실행 가능한 경계가 이미 구현되어 있으며, 2026-06-14에 `go test ./packages/domain/... ./services/worker/internal/jobs ./services/worker/internal/marketdata/importer ./services/worker/internal/socket ./services/api/internal/socket ./services/api/internal/workerclient ./apps/cli/internal/operator`가 통과했다.
- 완료 근거(freshness-status): `collection_freshness` operator scenario가 freshness status, missing count, latest date를 text/JSONL 출력과 handoff matrix에 포함하며, 2026-06-14에 `go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli`가 통과했다. 증거: `agent-task/archive/2026/06/m-backtest-data-collection-infrastructure/02+01_freshness_status/complete.log`.
- 완료 근거(provider-boundary): provider vocabulary에 KIS/KRX/DART/Yahoo data source id를 고정하고 `ProviderCapability`가 provider, venue, market, daily-bar timeframe 경계를 검증하도록 보강했다. 2026-06-14에 `go test -count=1 ./packages/domain/...`와 `go test -count=1 ./services/worker/internal/jobs`가 통과했다.
- 완료 근거(normalized-store): PostgreSQL bars schema와 SQL query contract가 normalized OHLCV 필드만 사용하고 raw provider payload column을 포함하지 않도록 guard test를 추가했다. 2026-06-14에 `go test -count=1 ./services/worker/internal/storage/postgres`가 통과했다.
- 완료 근거(gap-handling): `collection_freshness` scenario가 `expected_yyyymmdd` 기반 gap, duplicate, provider delay를 text/JSONL 출력과 expectation mismatch 검증에 포함하며, matched-zero-bars symbol의 double count regression을 보강했다. 2026-06-14에 `go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli`가 통과했다. 증거: `agent-task/archive/2026/06/m-backtest-data-collection-infrastructure/03+02_gap_handling/complete.log`.
- 완료 근거(headless-smoke): `backtest_run_polling` operator scenario가 named universe 기반 `import_daily_bars` 후 `start_backtest`와 `poll_backtest_run`으로 terminal 상태까지 확인하는 headless smoke를 문서화했다. 2026-06-14에 `go test -count=1 ./apps/cli/internal/operator ./apps/cli/internal/cli`가 통과했다.
- 작업 현황(input-selector): `01_input_selector_contract`는 selector contract/domain/forwarding 보존을 PASS 처리했다. 증거: `agent-task/archive/2026/06/m-backtest-data-collection-infrastructure/01_input_selector_contract/complete.log`.
- 작업 현황(input-selector): `02+01_storage_bar_selector`는 저장된 bar source와 engine selector filtering 검증을 PASS 처리했다. 증거: `agent-task/archive/2026/06/m-backtest-data-collection-infrastructure/02+01_storage_bar_selector/complete.log`.
- 작업 현황(input-selector): `03+01,02_backtest_selector_flow`는 `input-selector` Roadmap Target을 닫는 backtest selector flow를 PASS 처리했다. 증거: `agent-task/archive/2026/06/m-backtest-data-collection-infrastructure/03+01,02_backtest_selector_flow/complete.log`.
- 작업 현황(input-selector): 2026-06-15 기준 active task 디렉터리는 없으며, 전체 마일스톤은 사용자 완료 확인과 archive 승인 대기 상태다.
- 선행 작업: Backtest Engine Baseline, Backtest Analysis Surface
- 후속 작업: Backtest Scenario Automation, Data Quality Monitoring, Agent Tooling Bridge 후보
- 확인 필요: 없음
