toki/alt
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
alt/agent-task/m-backtest-multi-timeframe-coverage/02+01_kis_job_capability/PLAN-local-G06.md
toki 97373ca14e feat(agent-task): m-backtest-multi-timeframe-coverage 작업 계획과 코드 리뷰를 추가한다 
01_domain_capability_matrix: PLAN-local-G05, CODE_REVIEW-local-G05
02+01_kis_job_capability: PLAN-local-G06, CODE_REVIEW-local-G06
2026-06-17 21:37:12 +09:00

12 KiB
Raw Blame History

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:

// 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:

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을 확인한다.

중간 검증:

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:

// 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:

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을 추가한다.

중간 검증:

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

최종 검증

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

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

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