<!-- task=m-api-centered-proto-socket-rail/05+02_market_rail plan=0 tag=MARKET -->
# PLAN-cloud-G07: Market Data API to Worker Proto-Socket Rail

## 이 파일을 읽는 구현 에이전트에게
이 계획은 market data 조회와 status 성격의 요청을 API -> worker proto-socket rail 위에 얹는 작업이다. `02+01_worker_socket_rail` 완료 후 진행한다.

## 배경
`market.proto`에는 instruments와 bars 관련 요청/응답이 있고, worker storage에는 instrument/bar store port와 postgres 구현이 있다. API에는 market parser registration은 있지만 handler가 없고, client wrapper도 별도 계획에서 보강된다.

## 사용자 리뷰 요청 흐름
market data 조회를 위해 client가 worker 또는 DB에 직접 붙어야 한다는 요구가 나오면 중단한다. 이는 API-centered topology와 충돌한다.

## 분석 결과
### 읽은 파일
- `packages/contracts/proto/alt/v1/market.proto`
- `packages/contracts/proto/alt/v1/common.proto`
- `services/api/internal/socket/server.go`
- `services/api/internal/contracts/parser_map.go`
- `services/worker/internal/storage/ports.go`
- `services/worker/internal/storage/postgres/store.go`
- `services/worker/internal/storage/postgres/mapping.go`
- `services/worker/internal/storage/postgres/queries/queries.sql`
- `services/worker/internal/storage/postgres/store_test.go`

### 테스트 커버리지 공백
- instrument/bar store tests는 있으나 proto response mapping tests가 없다.
- API market handler tests가 없다.
- status 의미가 connection health인지 market ingestion/data availability인지 코드상 고정되어 있지 않다.

### 심볼 참조
- `ListInstrumentsRequest`: `packages/contracts/proto/alt/v1/market.proto:39`
- `ListBarsRequest`: `packages/contracts/proto/alt/v1/market.proto:48`
- `InstrumentStore`: `services/worker/internal/storage/ports.go:15`
- `BarStore`: `services/worker/internal/storage/ports.go:21`
- `ListInstruments`: `services/worker/internal/storage/postgres/store.go:60`
- `GetBars`: `services/worker/internal/storage/postgres/store.go:87`
- API parser map: `services/api/internal/contracts/parser_map.go:11`

### 분할 판단
market rail은 조회 중심이라 backtest보다 작지만 API/worker 양쪽 protocol handler와 mapping이 필요하다. status schema 결정이 포함될 수 있어 G07로 둔다.

### 범위 결정 근거
- market data read ownership은 worker/store 쪽에 두고 API는 control plane facade로 유지한다.
- provider/KIS 같은 외부 프로토콜은 프로젝트 규칙의 예외이며 이 계획의 범위가 아니다.
- status는 기존 common health/status contract를 우선 재사용하고, 부족할 때만 additive schema를 추가한다.

### 빌드 등급
- Build lane: `cloud-G07`
- Review lane: `cloud-G07`
- 근거: protocol handler와 data mapping을 추가하지만 execution command보다 위험도는 낮다.

## 구현 체크리스트
### [MARKET-1] API market handlers 추가
문제:
API socket server가 instruments/bars 요청을 받지 않는다.

해결 방법:
API registry에 market handlers를 추가하고 worker client를 통해 worker로 전달한다. API는 query validation과 error mapping만 담당한다.

수정 파일 및 체크리스트:
- `services/api/internal/socket/**`
- `services/api/internal/workerclient/**`
- `services/api/internal/contracts/**`
- [ ] list instruments handler 등록.
- [ ] list bars handler 등록.
- [ ] status 요청이 있다면 API/worker rail에서 의미가 명확히 분리된다.
- [ ] API가 worker storage를 직접 import하지 않는다.

테스트 작성:
- fake worker client 기반 API handler tests.
- invalid symbol/time range tests.
- worker error mapping tests.

중간 검증:
- 원격 검증 환경에서만 `go test ./services/api/...` 실행.

### [MARKET-2] worker market handlers 추가
문제:
worker store는 market data를 조회할 수 있지만 proto-socket request와 연결되어 있지 않다.

해결 방법:
worker socket server에 market query handlers를 추가하고 `InstrumentStore`, `BarStore` port를 사용한다.

수정 파일 및 체크리스트:
- `services/worker/internal/socket/**`
- `services/worker/internal/storage/**` 필요 시 mapping helper
- [ ] instruments response mapping 구현.
- [ ] bars response mapping 구현.
- [ ] empty data와 invalid range behavior가 계약과 일치한다.

테스트 작성:
- fake store 기반 worker handler tests.
- domain/store result -> proto response mapper tests.
- empty list and missing instrument tests.

중간 검증:
- 원격 검증 환경에서만 `go test ./services/worker/...` 실행.

### [MARKET-3] status contract 의미 확정
문제:
마일스톤에는 market data/status가 언급되지만 현재 status가 socket connectivity, worker health, data freshness 중 무엇인지 분명하지 않다.

해결 방법:
기존 `common.proto` health/status 계열 메시지를 먼저 검토한다. data freshness나 ingestion status가 별도 개념이면 additive market status request/response를 추가하고 parser/client/API/worker에 반영한다. 단순 연결 상태라면 client connection controller와 worker health로 처리하고 새 schema를 만들지 않는다.

수정 파일 및 체크리스트:
- 필요 시 `packages/contracts/proto/alt/v1/common.proto`
- 필요 시 `packages/contracts/proto/alt/v1/market.proto`
- 필요 시 generated contracts
- [ ] status 의미가 테스트명과 docs에 드러난다.
- [ ] 기존 schema 의미를 변경하지 않는다.
- [ ] parser map이 누락되지 않는다.

테스트 작성:
- status schema가 추가될 경우 parser map/contracts tests.
- status handler가 추가될 경우 API/worker tests.

중간 검증:
- 원격 검증 환경에서만 `bin/contracts-check` 실행.

## 수정 파일 요약
- 예상 API 코드: `services/api/internal/socket/**`, `services/api/internal/workerclient/**`
- 예상 worker 코드: `services/worker/internal/socket/**`, `services/worker/internal/storage/**`
- 조건부 contracts: `packages/contracts/proto/alt/v1/common.proto`, `packages/contracts/proto/alt/v1/market.proto`, generated outputs

## 최종 검증
- 원격 검증 환경에서만 `go test ./services/api/...`
- 원격 검증 환경에서만 `go test ./services/worker/...`
- 원격 검증 환경에서만 `bin/contracts-check`
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
