# Milestone: US Market Expansion

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/trading-expansion/PHASE.md`

## 목표

한국장 MVP에서 만든 provider-neutral market data와 backtest 구조 위에 미국장 데이터를 추가한다. KIS가 국내/해외를 모두 지원한다는 전제를 활용하되, 시장별 calendar, currency, venue 차이를 domain과 persistence에서 흡수한다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음
- 결정 내용:
  - [x] 미국장 MVP universe는 watchlist 중심으로 시작한다. ETF/개별주는 universe entry의 `asset_type` metadata로 표현하고, 구현은 특정 종목 종류에 고정하지 않는다.
  - [x] 초기 미국장 데이터 provider는 KIS로 고정한다. 다만 provider adapter/capability 형식은 유지해 Kiwoom 같은 후속 provider가 시장별 지원 범위를 선언할 수 있게 한다.

## 범위

- US market instrument mapping
- watchlist 기반 US market universe selector
- USD/NASDAQ/NYSE calendar handling
- daily bar import
- 한국장과 동일한 normalized data/query path
- backtest compatibility

## 기능

### Epic: [us-market] US market expansion

미국장 instrument, calendar, daily data, shared query, backtest compatibility 확장을 묶는다.

- [x] [us-instruments] 미국장 instrument identity와 provider symbol mapping이 있다. 검증: watchlist fixture가 `market=us`, `venue`, `currency=USD`, `asset_type` metadata와 provider symbol을 분리해 가진다. 근거: `agent-task/archive/2026/06/m-us-market-expansion/01_market_foundation/complete.log`
- [x] [us-calendar] 미국장 timezone/currency/venue 기준이 있다. 검증: market/currency/venue 차이가 domain model과 contracts에 일관되게 반영된다. 근거: `agent-task/archive/2026/06/m-us-market-expansion/01_market_foundation/complete.log`
- [x] [us-daily-bars] KIS를 초기 provider로 사용해 미국장 일봉 데이터를 normalized bar model로 저장한다. 검증: 한국장 pipeline을 깨지 않고 provider capability가 미국장 daily bar import를 허용한다. 근거: `agent-task/archive/2026/06/m-us-market-expansion/02+01_kis_us_daily_bars/complete.log`
- [x] [shared-query] 한국장과 미국장이 같은 query/contract pattern을 공유한다. 검증: market selector만 바꿔도 공통 query path를 사용한다. 근거: `agent-task/archive/2026/06/m-us-market-expansion/03+01_shared_query_surface/complete.log`
- [x] [us-backtest] 미국장 daily data로 backtest fixture 또는 smoke가 동작한다. 검증: `bin/test`와 관련 worker 검증이 통과한다. 근거: `agent-task/archive/2026/06/m-us-market-expansion/04+02,03_us_backtest_smoke/complete.log`

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-06
- 완료 근거: `us-instruments`, `us-calendar`, `us-daily-bars`, `shared-query`, `us-backtest`가 각 `agent-task/archive/2026/06/m-us-market-expansion/*/complete.log`의 Roadmap Completion 근거로 완료되었다.
- 완료 근거: `us-backtest`는 `go test -count=1 ./services/worker/internal/backtest ./apps/cli/internal/operator`, `go test -count=1 ./services/worker/...`, `bin/test`, `git diff --check` PASS로 검증되었다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자의 "현 마일스톤 종료" 요청에 따라 완료 승인 및 archive 이동을 수행한다.

## 범위 제외

- 미국장 실거래 주문
- 옵션/선물/FX
- 분봉/실시간 미국장 streaming

## 작업 컨텍스트

- 관련 경로: `services/worker/`, `packages/domain/market/`, `packages/contracts/proto/alt/v1/market.proto`
- 표준선(선택): 시장 추가는 provider adapter와 market metadata 확장으로 처리하고 백테스트 코어를 복제하지 않는다.
- 표준선(선택): universe는 watchlist 중심 selector로 두고, ETF/개별주는 instrument metadata의 `asset_type`으로 열어둔다.
- 표준선(선택): 초기 provider는 KIS로 고정하지만 provider abstraction은 유지한다. Provider는 `supported_markets`, `supported_venues`, `supported_asset_types`, `capabilities`를 선언하고, Kiwoom 같은 후속 provider는 한국장만 지원하더라도 같은 provider boundary에 붙일 수 있어야 한다.
- 표준선(선택): provider와 market은 별도 축이다. KIS가 한국장/미국장을 모두 지원하더라도 `provider=KIS`가 곧 `market=us`를 뜻하지 않으며, Kiwoom 추가 시 `provider=Kiwoom`, `market=kr` 조합처럼 capability matching으로 선택한다.
- 선행 작업: Korea Daily Data Foundation, Backtest Engine Baseline, Command-First Operator Workflow, Paper Trading Command Workflow
- 후속 작업: Live Trading Boundary, Flutter Operator Console MVP
- 확인 필요: 없음
