<!-- task=m-us-market-expansion/01_market_foundation plan=0 tag=US_FOUNDATION -->

# Code Review Reference - US_FOUNDATION

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation.
> Finalization is review-agent-only.

## 개요

date=2026-06-06
task=m-us-market-expansion/01_market_foundation, plan=0, tag=US_FOUNDATION

## Roadmap Targets

- Milestone: `agent-roadmap/phase/trading-expansion/milestones/us-market-expansion.md`
- Task ids:
  - `us-instruments`: 미국장 instrument identity와 provider symbol mapping
  - `us-calendar`: 미국장 timezone/currency/venue 기준
- Completion mode: check-on-pass

## 이 파일을 읽는 리뷰 에이전트에게

> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.

각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. 리뷰 완료는 판정 append, active plan/review log archive, PASS 시 `complete.log` 작성과 archive 이동까지 끝난 상태를 의미합니다. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터만 보고하고 roadmap 수정은 런타임 책임입니다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [US_FOUNDATION-1] Domain Asset Type And Market Metadata | [x] |
| [US_FOUNDATION-2] Contract And Storage Asset Type Round Trip | [x] |

## 구현 체크리스트

- [x] [US_FOUNDATION-1] domain market model에 `AssetType`과 market/venue metadata를 추가하고 KR/US fixture vocabulary를 갱신한다. 검증: watchlist fixture가 `market=us`, `venue`, `currency=USD`, `asset_type`, provider symbol을 분리해 가진다.
- [x] [US_FOUNDATION-2] contract와 PostgreSQL persistence가 `asset_type`을 round-trip하도록 schema/query/mapping/generated output을 갱신한다. 검증: market/currency/venue/asset_type 차이가 domain model과 contracts에 일관되게 반영된다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 코드리뷰 전용 체크리스트

> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block을 확인한다.
- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-us-market-expansion/01_market_foundation/`로 이동한다.
- [ ] PASS이고 task group이 `m-us-market-expansion`이면 완료 이벤트 메타데이터를 보고한다.
- [ ] PASS split 작업이면 이동 후 빈 active parent 처리 여부를 확인한다.
- [x] WARN/FAIL이면 user-review gate 확인 뒤 다음 active plan/review 또는 `USER_REVIEW.md`를 작성한다.

## 계획 대비 변경 사항

- 없음. 계획된 설계 및 구현 방법론을 온전히 따랐음.

## 주요 설계 결정

- `packages/domain/market/types.go` 내에 `AssetType` (equity, etf)과 `VenueMetadata` 를 추가하고, Venue를 Key로 메타데이터를 리턴하는 `GetVenueMetadata` 헬퍼 함수를 추가함.
- `common.proto`와 `market.proto`에 `AssetType` enum 및 `Instrument.asset_type` 필드를 반영하고, `bin/contracts-gen`을 통해 generated code를 갱신함.
- Postgres DB migration에 `000003_instrument_asset_type` 마이그레이션(up/down)을 추가하여 `instruments` 테이블에 `asset_type` 컬럼을 생성하고, sqlc query 및 Go mapper/socket mapper 코드를 수정하여 round-trip 매핑이 정상 작동하도록 구현함.

## 사용자 리뷰 요청

- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

## 리뷰어를 위한 체크포인트

- `asset_type`이 provider symbol과 섞이지 않고 별도 field로 round-trip되는지 확인한다.
- `.proto`와 generated output이 drift 없이 일치하는지 확인한다.
- storage migration이 기존 rows를 깨지 않는 default/null 정책을 갖는지 확인한다.
- US fixture가 equity와 ETF를 모두 표현하고 `currency=USD`를 보존하는지 확인한다.

## 검증 결과

### US_FOUNDATION-1 중간 검증
```text
$ go test -count=1 ./packages/domain/...
ok      git.toki-labs.com/toki/alt/packages/domain/backtest     0.002s
ok      git.toki-labs.com/toki/alt/packages/domain/market       0.003s

$ go test -count=1 ./services/worker/internal/providers/kis
ok      git.toki-labs.com/toki/alt/services/worker/internal/providers/kis      0.007s
```

### US_FOUNDATION-2 중간 검증
```text
$ bin/contracts-gen
(exit 0)

$ bin/contracts-check
(exit 0)

$ go test -count=1 ./packages/contracts/gen/go/...
?       git.toki-labs.com/toki/alt/packages/contracts/gen/go/alt/v1     [no test files]

$ go test -count=1 ./services/worker/internal/storage/postgres ./services/worker/internal/socket
ok      git.toki-labs.com/toki/alt/services/worker/internal/storage/postgres   0.073s
ok      git.toki-labs.com/toki/alt/services/worker/internal/socket      0.061s
```

### 최종 검증
```text
$ bin/contracts-gen
(exit 0)

$ bin/contracts-check
(exit 0)

$ go test -count=1 ./packages/domain/...
ok      git.toki-labs.com/toki/alt/packages/domain/backtest     0.002s
ok      git.toki-labs.com/toki/alt/packages/domain/market       0.003s

$ go test -count=1 ./packages/contracts/gen/go/...
?       git.toki-labs.com/toki/alt/packages/contracts/gen/go/alt/v1     [no test files]

$ go test -count=1 ./services/worker/internal/storage/postgres ./services/worker/internal/socket ./services/worker/internal/providers/kis
ok      git.toki-labs.com/toki/alt/services/worker/internal/storage/postgres   0.067s
ok      git.toki-labs.com/toki/alt/services/worker/internal/socket      0.073s
ok      git.toki-labs.com/toki/alt/services/worker/internal/providers/kis      0.016s

$ bin/worker-storage-check
Generating worker storage code via sqlc...
Generation complete.

$ bin/test
All tests passed!

$ git diff --check
(exit 0)
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**

## 코드리뷰 결과

- 종합 판정: FAIL
- 차원별 평가:
  - Correctness: Pass
  - Completeness: Fail
  - Test coverage: Fail
  - API contract: Pass
  - Code quality: Pass
  - Plan deviation: Fail
  - Verification trust: Pass
- 발견된 문제:
  - Required: [services/worker/internal/providers/kis/daily_itemchartprice_test.go](/config/workspace/alt/services/worker/internal/providers/kis/daily_itemchartprice_test.go:258)의 `TestProviderSymbolsFixtureVocabulary`는 각 instrument 값이 허용 enum 집합 안에 있는지만 확인합니다. 그래서 [services/worker/testdata/providers/kis/provider_symbols.sample.json](/config/workspace/alt/services/worker/testdata/providers/kis/provider_symbols.sample.json:5)에서 `AAPL`/`SPY` US watchlist 항목이나 `NASDAQ`/`USD`/`etf` fixture row가 제거되어도 KR equity fixture만 남아 있으면 테스트가 계속 통과합니다. `US_FOUNDATION-1`의 통합 검증 조건인 US watchlist, USD, venue, equity/ETF, KIS provider symbol 분리를 실제로 잠그도록 필수 instrument id와 field 값을 명시적으로 assert하세요.
- 다음 단계: user-review gate는 트리거하지 않는다. active plan/review를 archive하고 `REVIEW_US_FOUNDATION` follow-up PLAN/CODE_REVIEW를 작성한다.
