toki
cb8bdd3470
- Add .sops.yaml for SOPS encryption configuration - Add kis-live-secret-guide.md with setup instructions - Add kis-live-secret-handoff.md for secret handoff procedure - Add secrets/kis.live.sops.yaml with encrypted credentials - Update kis-live-data-collection-pipeline milestone document
82 lines
5.6 KiB
Markdown
82 lines
5.6 KiB
Markdown
# Milestone: KIS Live Data Collection Pipeline
|
|
|
|
## 위치
|
|
|
|
- Roadmap: `agent-roadmap/ROADMAP.md`
|
|
- Phase: `agent-roadmap/phase/operator-surface/PHASE.md`
|
|
|
|
## 목표
|
|
|
|
Flutter 실화면 구현 전에 한국투자증권(KIS) API를 실제 provider로 사용해 한국장 일봉 데이터를 수집하고, worker import/storage/backtest 입력 경계까지 이어지는 운영 파이프라인을 검증한다. 기존 fixture/mock 기반 KIS adapter와 provider-neutral pipeline은 유지하되, live credential, token/auth, quota/error, sanitized smoke evidence를 별도 runtime 경계로 정리한다.
|
|
|
|
## 상태
|
|
|
|
[계획]
|
|
|
|
## 구현 잠금
|
|
|
|
- 상태: 잠금
|
|
- 결정 필요: 아래 체크리스트
|
|
- [ ] KIS live smoke에 사용할 credential 주입 방식을 정한다. 원문 secret, 1Password item/vault 이름, 계좌번호는 tracked 문서에 기록하지 않는다.
|
|
- [ ] live smoke 대상 범위를 정한다: 국내주식 일봉 `inquire-daily-itemchartprice` 단일 symbol/date range부터 시작한다.
|
|
- [ ] live 호출 결과를 commit 가능한 sanitized fixture/evidence로 남기는 기준을 정한다.
|
|
|
|
## 범위
|
|
|
|
- KIS REST auth/token 발급과 갱신 경계
|
|
- KIS 국내주식 일봉 조회 REST client
|
|
- runtime secret injection boundary
|
|
- quota/rate-limit, auth failure, unavailable, malformed response 상태 분류
|
|
- live response를 sanitized fixture/evidence로 남기는 절차
|
|
- worker market data importer와 실제 KIS provider 연결
|
|
- KIS live smoke가 import/storage/backtest 입력 조회까지 이어지는 end-to-end 검증
|
|
- UI MVP가 의존할 market data availability/status evidence
|
|
|
|
## 기능
|
|
|
|
### Epic: [kis-live] KIS live market data collection
|
|
|
|
fixture/mock 기반 adapter를 실제 KIS provider 호출과 worker import pipeline으로 확장한다.
|
|
|
|
- [ ] [credential-boundary] KIS credential과 token을 runtime-only secret으로 주입한다. 검증: tracked 파일에 secret, item/vault 이름, 계좌번호가 남지 않고, 미설정 시 명확한 unavailable 상태가 나온다.
|
|
- [ ] [auth-client] KIS auth/token client가 국내주식 일봉 호출에 필요한 access token을 얻고 만료/오류 상태를 분류한다. 검증: fake auth response unit test와 credential 없는 unavailable test가 통과한다.
|
|
- [ ] [daily-rest-client] KIS `inquire-daily-itemchartprice` REST client가 request parameter, response decode, error/quota/malformed 상태를 처리한다. 검증: 로컬 KIS 공식 샘플 cache와 sanitized fixture 기반 test가 통과한다.
|
|
- [ ] [live-provider] worker market data importer가 KIS live provider를 선택해 일봉 데이터를 fetch할 수 있다. 검증: fake HTTP/live-gated smoke가 provider request, normalized bars, storage upsert를 확인한다.
|
|
- [ ] [live-smoke] credential이 준비된 환경에서 단일 symbol/date range KIS live smoke를 실행하고 sanitized evidence를 남긴다. 검증: 실제 KIS 호출 결과가 raw secret 없이 저장/조회되고, 실패 시 auth/quota/unavailable 원인이 grep 가능한 상태로 남는다.
|
|
- [ ] [backtest-input] KIS live로 수집한 normalized daily bars가 backtest 입력 조회 경계에서 사용 가능하다. 검증: 저장된 bars를 backtest fixture/input query가 읽을 수 있음을 smoke 또는 test로 확인한다.
|
|
- [ ] [operator-handoff] Flutter Operator Console MVP로 넘길 provider readiness와 market data status key를 정리한다. 검증: 실행 명령, secret 주입 전제, sanitized evidence 경로, unavailable/error 상태를 문서화한다.
|
|
|
|
## 완료 리뷰
|
|
|
|
- 상태: 없음
|
|
- 요청일: 없음
|
|
- 완료 근거: 아직 live KIS provider pipeline과 credential-gated smoke evidence가 없다.
|
|
- 리뷰 필요:
|
|
- [ ] 사용자가 완료 결과를 확인했다
|
|
- [ ] archive 이동을 승인했다
|
|
- 리뷰 코멘트: 없음
|
|
|
|
## 범위 제외
|
|
|
|
- Flutter 실화면 구현
|
|
- 미국장 데이터 수집
|
|
- 분봉/틱/실시간 streaming
|
|
- 실거래 주문 API
|
|
- 계좌/잔고/주문 체결 조회
|
|
- production 자동 수집 스케줄링
|
|
- secret 원문, 1Password item/vault 이름, 계좌번호의 tracked 문서 기록
|
|
|
|
## 작업 컨텍스트
|
|
|
|
- 관련 경로: `services/worker/`, `services/worker/internal/providers/kis/`, `services/worker/internal/marketdata/`, `services/worker/testdata/providers/kis/`, `packages/domain/market/`, `apps/client/`
|
|
- 표준선(선택): 기존 provider-neutral importer/storage/backtest 입력 경계를 유지하고, KIS 특수성은 provider adapter와 runtime config에 격리한다.
|
|
- 표준선(선택): KIS 공식 샘플은 tracked source dependency가 아니라 local cache 참조로 사용한다. private rule의 `.agent-cache/koreainvestment/open-trading-api` 경계를 따른다.
|
|
- 표준선(선택): live smoke는 credential이 준비된 환경에서만 실행하며, credential 미설정 상태는 실패가 아니라 `unavailable` evidence로 남긴다.
|
|
- 표준선(선택): 원격 field secret boundary는 Vaultwarden container와 host-only `sops`/`age`로 둔다. code-server 컨테이너에는 age private key나 평문 secret 파일을 두지 않고, host wrapper가 `sops exec-env`로 필요한 환경변수만 주입해 smoke를 실행한다.
|
|
- 표준선(선택): Vaultwarden 접속 경로, host 경로, age key 위치 같은 환경 세부는 private testing rule에만 두고 tracked roadmap에는 raw secret, 계좌번호, item/vault 이름을 기록하지 않는다.
|
|
- 선행 작업: Korea Daily Data Foundation, Backtest Engine Baseline, Operator Client API/Core Integration Validation
|
|
- 후속 작업: Flutter Operator Console MVP
|
|
- 확인 필요:
|
|
- live smoke credential 주입 방식
|
|
- sanitized live evidence 보관 기준
|
|
- 최초 symbol/date range
|