# Milestone: Korea Daily Data Foundation

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/data-foundation/PHASE.md`

## 목표

주식형 instrument의 일봉 데이터를 첫 MVP market data로 삼아 provider-neutral import, normalization, persistence 파이프라인을 만든다. 한국장/KIS는 첫 provider와 venue 검증 단위로 보되, domain model은 특정 장이나 KIS 응답 필드에 종속되지 않게 유지한다. Crypto는 현재 core 주식 모델 범위에서 제외하고, 향후 별도 asset-class domain에서 공유 가능한 일부 파이프라인만 재사용할지 검토한다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음
- 확정된 기준:
  - 주식/ETF/지수처럼 주식시장 개념을 공유하는 instrument를 venue-agnostic core 대상으로 둔다.
  - Crypto는 현재 core 주식 모델에 포함하지 않고, 나중에 별도 asset-class domain으로 분리 검토한다.
  - Universe는 watchlist, exchange-wide, sector-like selector를 갈아 끼울 수 있는 provider-neutral selector로 설계하고, 특정 selector를 instrument identity에 박지 않는다.
  - 현재 검증은 KIS credential 없는 mock/fixture 테스트를 우선한다.
  - 실제 KIS smoke 단계에서만 credential을 준비하며, 그때도 `.env`가 아니라 1Password CLI 또는 service account 기반 runtime injection으로 제공한다.
  - KIS adapter mapping 참조는 로컬 cache의 공식 API 샘플 repo를 우선하고, Postman export는 필수 입력으로 보지 않는다.
  - KIS mock/sample 데이터는 secret을 제거한 JSON artifact로 보관하고, SQLite는 대량 fixture 검색이 필요해진 뒤 검토한다.

## 범위

- KRX/Korea daily bar import pipeline as the first venue path
- venue-agnostic equity instrument identity and provider symbol mapping
- provider-neutral universe selector
- normalized instrument/bar storage
- trading calendar/timezone/currency 기본 처리
- KIS adapter boundary
- local KIS API sample repo reference handling
- sanitized mock/sample response artifact handling
- deferred 1Password-injected secret boundary for live smoke
- fixture 또는 mock provider를 통한 credential 없는 검증 경로

## 기능

### Epic: [market-data] Korea daily market data

한국장 일봉 데이터의 provider-neutral 수집, 정규화, 저장, 검증 흐름을 묶는다.

- [x] [instrument-map] provider symbol과 ALT의 venue-agnostic equity instrument identity를 매핑한다.
- [x] [universe-selector] watchlist, exchange-wide, sector-like 입력을 provider-neutral universe selector로 다룬다.
- [x] [daily-bars] 한국장 일봉 OHLCV를 normalized bar 모델로 저장한다. 검증: 선택된 equity universe의 일봉 입력이 저장소에 들어가고, 같은 입력을 다시 import해도 중복/갱신 정책이 일관된다.
- [x] [calendar-rules] `Asia/Seoul`, KRX, KRW 기준의 최소 calendar/currency 처리를 갖는다.
- [x] [kis-adapter] KIS provider adapter 경계가 worker 내부에 격리된다. 검증: 로컬 cache의 KIS API 샘플 repo와 sanitized mock/sample response를 기준으로 request/auth/response mapping을 확정할 수 있고 secret 값은 저장하지 않는다.
- [x] [mock-provider] KIS credential 없이도 pipeline을 검증할 fixture/mock provider가 있다.
- [x] [data-check] import 결과를 재현 가능하게 검증하는 테스트 또는 CLI/smoke 명령이 있다. 검증: normalized data가 backtest milestone에서 소비 가능한 형태로 조회되고 `bin/test`와 관련 worker 검증이 통과한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-05-29
- 완료 근거:
  - provider-neutral `market` model, universe selector, storage/importer, KIS fixture normalization, mock data-check smoke가 구현되어 모든 기능 Task가 `[x]`로 정리되었다.
  - `agent-task/m-korea-daily-data-foundation/03+01,02_data_check_smoke` PASS 완료 이벤트가 반영되었고, 최종 archive는 `agent-task/archive/2026/05/m-korea-daily-data-foundation/03+01,02_data_check_smoke`에 있다.
  - `bin/test`가 통과했고 generated contract diff가 비어 있어 data-check 검증 조건을 충족했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-05-29 사용자 승인에 따라 `[완료]`로 전환하고 Milestone archive 이동을 수행한다.

## 범위 제외

- 미국장 데이터 수집
- 분봉/틱/실시간 streaming
- 실거래 주문 API
- 고급 corporate action adjustment
- crypto/디지털 자산 core model 통합
- 실제 KIS secret 값 저장 또는 문서화

## 작업 컨텍스트

- 관련 경로: `services/worker/`, `services/worker/testdata/providers/kis/`, `packages/domain/market/`, `packages/contracts/proto/alt/v1/market.proto`
- 표준선(선택): 첫 데이터 단위는 일봉이고, 구조는 분봉/실시간 확장을 막지 않는다.
- 표준선(선택): canonical model은 global equity venue-agnostic vocabulary를 우선하고, 한국장/KIS 특수 필드는 adapter, venue metadata, raw payload, 또는 명시적 extension metadata에 격리한다.
- 표준선(선택): KIS API mapping은 로컬 cache의 공식 샘플 repo를 먼저 보고, mock/sample artifact는 sanitized JSON을 기본으로 둔다. SQLite는 대량 fixture 검색이나 쿼리 비교가 필요해질 때 도입한다.
- 표준선(선택): mock/fixture 테스트에는 KIS credential이 필요 없다. 실제 KIS smoke 단계에서만 1Password CLI 또는 service account로 실행 시점에 주입하며 `.env`에 저장하지 않는다.
- 선행 작업: Persistence and Worker Backbone
- 후속 작업: Backtest Engine Baseline
- 확인 완료: mock 테스트에는 sanitized KIS daily bar fixture와 expected normalized bar 사례를 사용한다.
