<!-- task=m-backtest-multi-timeframe-coverage/02+01_kis_job_capability plan=0 tag=API -->

# Plan - API

## 이 파일을 읽는 구현 에이전트에게

이 subtask는 `01_domain_capability_matrix` 완료 후에만 구현한다. 시작 전에 `agent-task/m-backtest-multi-timeframe-coverage/01_domain_capability_matrix/complete.log` 또는 archive의 같은 subtask `complete.log`가 있는지 확인한다. `CODE_REVIEW-local-G06.md`의 구현 에이전트 소유 섹션을 채우는 것이 구현의 마지막 단계다. 선택된 SDD 결정 또는 Milestone `구현 잠금 > 결정 필요` 항목이 막으면 리뷰 stub의 `사용자 리뷰 요청`만 채우고 멈춘다. 구현 중 사용자에게 직접 질문하거나 `USER_REVIEW.md`, `complete.log`, log archive를 만들지 않는다.

## 배경

domain foundation이 생긴 뒤에는 KIS provider capability와 daily import job gate가 같은 matrix 판정을 쓰도록 연결해야 한다. SDD S02는 KIS KR/US daily, minute, monthly 조합의 accepted/rejected case와 거부 사유를 요구한다. 이 plan은 `capability-matrix` Milestone Task와 SDD S02 완료를 목표로 한다.

## 사용자 리뷰 요청 흐름

사용자 리뷰 요청은 선택된 SDD 결정 또는 선택된 Milestone lock 결정이 실구현을 차단할 때만 active `CODE_REVIEW-local-G06.md`의 `사용자 리뷰 요청` 섹션에 기록한다. 직접 chat 질문은 금지이며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 판단한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md`
- Task ids:
  - `capability-matrix`: provider, market, venue, asset type, timeframe별 지원/미지원 사유를 capability matrix로 표현한다.
- Completion mode: check-on-pass

## Spec Targets

- SDD: `agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md`
- Acceptance scenarios:
  - `S02`: task=`capability-matrix`; evidence=`capability matrix accepted/rejected tests for KIS KR/US daily, minute, monthly with explicit rejection reasons`
- Completion mode: spec-check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/roadmap-sdd/SKILL.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/backtest-loop/PHASE.md`
- `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md`
- `agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md`
- `agent-ops/rules/project/domain/domain-model/rules.md`
- `agent-ops/rules/project/domain/worker/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/domain-model-smoke.md`
- `agent-test/local/worker-smoke.md`
- `packages/domain/market/types.go`
- `packages/domain/market/types_test.go`
- `services/worker/internal/jobs/marketdata_jobs.go`
- `services/worker/internal/jobs/marketdata_jobs_test.go`
- `services/worker/internal/providers/kis/daily_itemchartprice.go`
- `services/worker/internal/providers/kis/daily_itemchartprice_test.go`
- `services/worker/cmd/alt-worker/main.go`
- `services/worker/cmd/alt-worker/main_test.go`

### 테스트 환경 규칙

- test_env: `local`
- env rules: `agent-test/local/rules.md` 존재 및 정독 완료
- matched profiles: `agent-test/local/domain-model-smoke.md`, `agent-test/local/worker-smoke.md`
- 적용 명령: `go test ./packages/domain/...`, `go test ./services/worker/...`
- fallback: 없음

### 테스트 커버리지 공백

- 현재 `services/worker/internal/providers/kis/daily_itemchartprice_test.go`는 normalized daily bars와 provider symbol fixture를 검증하지만 KIS capability accepted/rejected matrix를 검증하지 않는다.
- 현재 `services/worker/internal/jobs/marketdata_jobs_test.go`는 daily import accepted/rejected를 old daily gate로 검증한다. monthly/minute rejected reason과 asset type 차원은 없다.

### 심볼 참조

- 변경 대상 심볼: `kis.Capability`, `jobs.RegisterDailyBarImportHandler`, `market.ProviderCapability` matrix API
- call sites:
  - `services/worker/cmd/alt-worker/main.go`
  - `services/worker/internal/jobs/marketdata_jobs.go`
  - `services/worker/internal/jobs/marketdata_jobs_test.go`
  - `services/worker/internal/providers/kis/daily_itemchartprice.go`
  - `services/worker/internal/providers/kis/daily_itemchartprice_test.go`

### 분할 판단

- split decision policy를 plan 파일 선택 전에 적용했다.
- shared task group: `agent-task/m-backtest-multi-timeframe-coverage/`
- current subtask: `02+01_kis_job_capability`
- dependency: predecessor index `01` = `agent-task/m-backtest-multi-timeframe-coverage/01_domain_capability_matrix`
- predecessor status: active sibling plan exists, `complete.log` missing at plan creation time. 구현자는 시작 전에 active 또는 archive `complete.log`를 확인해야 한다.

### 범위 결정 근거

- 포함: KIS capability table, worker daily import job capability gate, related tests.
- 제외: `.proto` 변경, API request shape 변경, CLI surface 변경, actual minute import endpoint, monthly aggregation generation, storage schema 변경. Monthly는 이 task에서 provider direct import rejected reason으로만 다룬다.

### 빌드 등급

- build: `local-G06`
- review: `local-G06`
- 근거: domain foundation 후 worker/KIS rollout이며 verification이 local Go tests로 닫힌다. 다만 Milestone Task와 SDD S02 completion을 주장하므로 G06으로 둔다.

## 구현 체크리스트

- [ ] `01_domain_capability_matrix`의 `complete.log`가 active 또는 archive 경로에 있는지 확인하고, 없으면 구현하지 않고 dependency missing을 리뷰 stub에 기록한다.
- [ ] `kis.Capability()`를 KIS KR/US daily accepted, monthly/minute_1/minute_5 rejected reason을 표현하는 matrix로 갱신한다.
- [ ] `RegisterDailyBarImportHandler`가 새 matrix API로 daily import gate를 통과시키고 rejected reason을 `daily bar import payload` error에 보존하게 한다.
- [ ] KIS capability와 job handler tests에 KR/US daily accepted, monthly/minute rejected, asset type accepted/rejected case를 추가한다. 검증: KIS KR/US daily, minute, monthly 조합의 accepted/rejected case가 명시적으로 통과한다.
- [ ] `go test ./packages/domain/...`와 `go test ./services/worker/...`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

`02+01_kis_job_capability`는 directory name 기준으로 predecessor `01_domain_capability_matrix`에 의존한다. 구현 시작 전 다음 중 하나가 있어야 한다.

- active: `agent-task/m-backtest-multi-timeframe-coverage/01_domain_capability_matrix/complete.log`
- archive: `agent-task/archive/*/*/m-backtest-multi-timeframe-coverage/01_domain_capability_matrix/complete.log`

### [API-1] KIS capability matrix rollout

문제:
`services/worker/internal/providers/kis/daily_itemchartprice.go:32`의 `Capability()`는 venue map과 daily timeframe map만 반환한다. SDD S02의 KIS KR/US daily, minute, monthly accepted/rejected case와 거부 사유를 표현하지 못한다.

해결 방법:
`01_domain_capability_matrix`에서 만든 matrix API로 `kis.Capability()`를 작성한다. KR/KRX equity daily, US/NASDAQ equity daily, US/NASDAQ ETF daily는 accepted로 둔다. `monthly`는 D02에 따라 provider direct source가 아니라 daily aggregation source라는 reason으로 rejected한다. `minute_1`/`minute_5`는 이번 task에서 provider daily import gate 미지원 reason으로 rejected한다.

Before:

```go
// services/worker/internal/providers/kis/daily_itemchartprice.go:32
func Capability() market.ProviderCapability {
	return market.ProviderCapability{
		Provider: market.ProviderKIS,
		Venues: map[market.Venue]bool{
			market.VenueKRX:    true,
			market.VenueNASDAQ: true,
			market.VenueNYSE:   true,
		},
		Timeframes: map[market.Timeframe]bool{
			market.TimeframeDaily: true,
		},
	}
}
```

After:

```go
func Capability() market.ProviderCapability {
	return market.ProviderCapability{
		Provider: market.ProviderKIS,
		Rules: []market.ProviderCapabilityRule{
			{Market: market.MarketKR, Venue: market.VenueKRX, AssetTypes: ..., Timeframes: ...},
			{Market: market.MarketUS, Venue: market.VenueNASDAQ, AssetTypes: ..., Timeframes: ...},
			{Market: market.MarketUS, Venue: market.VenueNYSE, AssetTypes: ..., Timeframes: ...},
		},
	}
}
```

수정 파일 및 체크리스트:

- [ ] `services/worker/internal/providers/kis/daily_itemchartprice.go`: `Capability()`를 matrix API로 갱신
- [ ] `services/worker/internal/providers/kis/daily_itemchartprice_test.go`: KIS matrix accepted/rejected 테스트 추가

테스트 작성:
`TestKISCapabilityMatrixDailyAcceptedAndTimeframeRejections`를 추가한다. `market.ProviderCapabilityRequest` 또는 01에서 만든 동등한 request로 KR/KRX equity daily, US/NASDAQ equity daily, US/NASDAQ ETF daily accepted를 확인하고, KR/US monthly, minute_1, minute_5 rejected reason을 확인한다.

중간 검증:

```bash
go test ./services/worker/internal/providers/kis
```

기대 결과: exit code 0.

### [API-2] Worker import job gate integration

문제:
`services/worker/internal/jobs/marketdata_jobs.go:113`은 old daily-only `RequireDailyBars`를 호출한다. 새 matrix API가 생겨도 worker job gate가 accepted/rejected reason을 직접 검증하지 않으면 SDD S02 증거가 job boundary까지 이어지지 않는다.

해결 방법:
`RegisterDailyBarImportHandler`가 payload selector를 capability request로 변환해 daily import gate를 검사한다. payload에 asset type이 없으므로 daily import job은 empty asset type을 wildcard 또는 unknown으로 넘긴다. rejected reason은 `fmt.Errorf("daily bar import payload: %w", err)` 형태로 보존한다. 기존 daily import payload schema는 바꾸지 않는다.

Before:

```go
// services/worker/internal/jobs/marketdata_jobs.go:113
if err := capability.RequireDailyBars(market.Provider(p.Provider), p.selector()); err != nil {
	return fmt.Errorf("daily bar import payload: %w", err)
}
```

After:

```go
decision := capability.CheckBars(market.ProviderCapabilityRequest{
	Provider:  market.Provider(p.Provider),
	Market:    market.Market(p.Market),
	Venue:     market.Venue(p.Venue),
	Timeframe: market.TimeframeDaily,
})
if !decision.Accepted {
	return fmt.Errorf("daily bar import payload: %s", decision.Reason)
}
```

수정 파일 및 체크리스트:

- [ ] `services/worker/internal/jobs/marketdata_jobs.go`: new matrix gate 사용
- [ ] `services/worker/internal/jobs/marketdata_jobs_test.go`: helper capability를 matrix API로 갱신
- [ ] `services/worker/internal/jobs/marketdata_jobs_test.go`: unsupported monthly/minute reason은 domain/KIS matrix에서 검증하고, job handler는 daily import payload rejection behavior를 유지하도록 테스트
- [ ] `services/worker/cmd/alt-worker/main.go`: `kis.Capability()` call site compile 확인

테스트 작성:
기존 `TestRegisterDailyBarImportHandlerDispatchesImporter`, `TestRegisterDailyBarImportHandlerDispatchesUSWatchlist`, `TestRegisterDailyBarImportHandlerRejectsUnsupportedVenue`를 새 matrix helper로 갱신한다. rejected error message에 capability reason이 남는 assertion을 추가한다.

중간 검증:

```bash
go test ./services/worker/internal/jobs ./services/worker/cmd/alt-worker
```

기대 결과: exit code 0.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `services/worker/internal/providers/kis/daily_itemchartprice.go` | API-1 |
| `services/worker/internal/providers/kis/daily_itemchartprice_test.go` | API-1 |
| `services/worker/internal/jobs/marketdata_jobs.go` | API-2 |
| `services/worker/internal/jobs/marketdata_jobs_test.go` | API-2 |
| `services/worker/cmd/alt-worker/main.go` | API-2 |

## 최종 검증

```bash
go test ./packages/domain/... ./services/worker/...
```

기대 결과: exit code 0. Go test cache output은 허용한다.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
