diff --git a/agent-roadmap/phase/operator-surface/milestones/operator-client-api-core-integration.md b/agent-roadmap/archive/phase/operator-surface/milestones/operator-client-api-core-integration.md similarity index 51% rename from agent-roadmap/phase/operator-surface/milestones/operator-client-api-core-integration.md rename to agent-roadmap/archive/phase/operator-surface/milestones/operator-client-api-core-integration.md index 64778e4..ee649b8 100644 --- a/agent-roadmap/phase/operator-surface/milestones/operator-client-api-core-integration.md +++ b/agent-roadmap/archive/phase/operator-surface/milestones/operator-client-api-core-integration.md @@ -11,7 +11,7 @@ Flutter 실화면 구현 전에 client core, provider, repository 경계에서 A ## 상태 -[진행중] +[완료] ## 구현 잠금 @@ -34,22 +34,22 @@ Flutter 실화면 구현 전에 client core, provider, repository 경계에서 A 운영 화면을 만들기 전에 Flutter client 내부의 API 연결과 기본 호출 경계를 화면 없이 검증한다. -- [ ] [client-contracts] generated/mapped contracts를 client core에서 사용할 수 있게 정리한다. 검증: Flutter/Dart test가 request/response mapping을 확인한다. -- [ ] [socket-core] API socket 연결, 해제, timeout 상태를 화면 없는 client state로 표현한다. 검증: fake 또는 local socket 기반 test가 상태 전이를 확인한다. -- [ ] [market-call] market data status/list 기본 API 호출을 client core에서 수행할 수 있다. 검증: test가 request payload와 parsed result/status key를 확인한다. -- [ ] [backtest-call] backtest list/detail/result/start 기본 API 호출을 client core에서 수행할 수 있다. 검증: test가 success result와 typed error mapping을 확인한다. -- [ ] [error-core] unavailable/error/disconnected 상태가 UI copy가 아닌 안정적인 client state로 남는다. 검증: typed error와 transport failure unit test가 통과한다. -- [ ] [handoff] Flutter Operator Console MVP로 넘길 API/core readiness evidence를 정리한다. 검증: 실행 명령, fixture/fake, 기대 상태, 남은 wireframe 의존성을 문서화한다. +- [x] [client-contracts] generated/mapped contracts를 client core에서 사용할 수 있게 정리한다. 검증: Flutter/Dart test가 request/response mapping을 확인한다. +- [x] [socket-core] API socket 연결, 해제, timeout 상태를 화면 없는 client state로 표현한다. 검증: fake 또는 local socket 기반 test가 상태 전이를 확인한다. +- [x] [market-call] market data status/list 기본 API 호출을 client core에서 수행할 수 있다. 검증: test가 request payload와 parsed result/status key를 확인한다. +- [x] [backtest-call] backtest list/detail/result/start 기본 API 호출을 client core에서 수행할 수 있다. 검증: test가 success result와 typed error mapping을 확인한다. +- [x] [error-core] unavailable/error/disconnected 상태가 UI copy가 아닌 안정적인 client state로 남는다. 검증: typed error와 transport failure unit test가 통과한다. +- [x] [handoff] Flutter Operator Console MVP로 넘길 API/core readiness evidence를 정리한다. 검증: 실행 명령, fixture/fake, 기대 상태, 남은 wireframe 의존성을 문서화한다. ## 완료 리뷰 -- 상태: 없음 -- 요청일: 없음 -- 완료 근거: 아직 기능 Task와 검증이 충족되지 않았다. +- 상태: 승인됨 +- 요청일: 2026-06-02 +- 완료 근거: `01_contract_mapping`, `02+01_socket_state`, `03+01_market_repository`, `04+02,03_backtest_error` 완료 로그가 `client-contracts`, `socket-core`, `market-call`, `backtest-call`, `error-core` Task의 PASS evidence를 남겼고, 아래 handoff evidence에 Flutter Operator Console MVP로 넘길 실행 명령/fixture/기대 상태/남은 wireframe 의존성을 정리했다. - 리뷰 필요: - - [ ] 사용자가 완료 결과를 확인했다 - - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 없음 + - [x] 사용자가 완료 결과를 확인했다 + - [x] archive 이동을 승인했다 +- 리뷰 코멘트: 사용자 요청으로 현재 마일스톤을 완료 처리하고 archive 이동한다. ## 범위 제외 @@ -66,3 +66,22 @@ Flutter 실화면 구현 전에 client core, provider, repository 경계에서 A - 선행 작업: Flutter Operator Console UX Plan, Operator Headless Workflow Validation - 후속 작업: Flutter Operator Console MVP - 확인 필요: 없음 + +## API/Core Readiness Handoff + +- 실행 명령: + - `cd apps/client && flutter test test/contracts/alt_api_result_test.dart` + - `cd apps/client && flutter test test/integrations/socket/socket_connection_controller_test.dart` + - `cd apps/client && flutter test test/features/market/market_repository_test.dart` + - `cd apps/client && flutter test test/features/backtest/backtest_repository_test.dart` + - `cd apps/client && flutter test` +- fixture/fake: + - contract mapping은 generated protobuf response의 populated/unset `ErrorInfo`와 unsupported response type을 unit test fixture로 사용한다. + - socket state는 fake/local socket controller transition test로 connect, handshake, timeout, explicit disconnect, socket close callback 상태를 확인한다. + - market/backtest repository는 fake `WebSocket`과 `PacketBase` round trip으로 request payload, decoded success response, typed `ErrorInfo`, timeout, decode failure, disconnected 상태를 확인한다. +- 기대 상태: + - client core는 UI copy 없이 `AltApiResult`, `AltApiError`, `AltTransportKind`, `SocketConnectionState`로 success/error/transport state를 보존한다. + - `MarketRepository`는 `listInstruments`, `listBars`를 `AltApiResult`로 반환한다. + - `BacktestRepository`는 `listBacktestRuns`, `getBacktestRunDetail`, `getBacktestResult`, `startBacktest`를 `AltApiResult`로 반환한다. +- 남은 wireframe 의존성: + - Flutter Operator Console MVP 화면 구성, dashboard depth, chart/form visual design, navigation 확정은 이 마일스톤 범위 밖이며 wireframe 승인 뒤 후속 마일스톤에서 처리한다. diff --git a/agent-roadmap/current.md b/agent-roadmap/current.md index 8f2aed7..27e8723 100644 --- a/agent-roadmap/current.md +++ b/agent-roadmap/current.md @@ -7,9 +7,9 @@ ## 활성 Milestone -- [진행중] Operator Client API/Core Integration Validation +- [계획] KIS Live Data Collection Pipeline - Phase: `agent-roadmap/phase/operator-surface/PHASE.md` - - 경로: `agent-roadmap/phase/operator-surface/milestones/operator-client-api-core-integration.md` + - 경로: `agent-roadmap/phase/operator-surface/milestones/kis-live-data-collection-pipeline.md` ## 선택 규칙 diff --git a/agent-roadmap/phase/operator-surface/PHASE.md b/agent-roadmap/phase/operator-surface/PHASE.md index 7e719c3..6f7bb06 100644 --- a/agent-roadmap/phase/operator-surface/PHASE.md +++ b/agent-roadmap/phase/operator-surface/PHASE.md @@ -25,9 +25,12 @@ Flutter client를 ALT의 공식 operator surface로 삼아 market data 상태와 - [완료] Operator Headless Workflow Validation - 경로: `agent-roadmap/archive/phase/operator-surface/milestones/operator-headless-workflow-validation.md` - 요약: Flutter 화면 없이 terminal/YAML 기반 운영 시나리오로 market data와 backtest 조회/실행 결과를 먼저 검증한다. -- [진행중] Operator Client API/Core Integration Validation - - 경로: `agent-roadmap/phase/operator-surface/milestones/operator-client-api-core-integration.md` - - 요약: Flutter 실화면 전에 client core/provider/repository 경계에서 API socket 연결과 기본 market/backtest 호출을 검증한다. +- [완료] Operator Client API/Core Integration Validation + - 경로: `agent-roadmap/archive/phase/operator-surface/milestones/operator-client-api-core-integration.md` + - 요약: Flutter 실화면 전에 client core/provider/repository 경계에서 API socket 연결과 기본 market/backtest 호출을 검증했다. +- [계획] KIS Live Data Collection Pipeline + - 경로: `agent-roadmap/phase/operator-surface/milestones/kis-live-data-collection-pipeline.md` + - 요약: Flutter 실화면 전에 KIS 실 API 기반 한국장 일봉 수집, worker import/storage, backtest 입력 경계까지 검증한다. - [보류] Flutter Operator Console MVP - 경로: `agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md` - 요약: headless 운영 검증과 화면 wireframe 승인 뒤에만 Flutter에서 market data, backtest run, result를 조회하고 실행 요청할 수 있는 MVP 화면을 구현한다. diff --git a/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md b/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md index f40ac88..4df5d06 100644 --- a/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md +++ b/agent-roadmap/phase/operator-surface/milestones/flutter-operator-console-mvp.md @@ -18,7 +18,8 @@ - 상태: 잠금 - 결정 필요: 아래 체크리스트 - [x] `Operator Headless Workflow Validation`이 완료되어 화면 없이 대표 운영 흐름을 검증했다. - - [ ] `Operator Client API/Core Integration Validation`이 완료되어 Flutter 실화면 없이 client core에서 기본 API 호출을 검증했다. + - [x] `Operator Client API/Core Integration Validation`이 완료되어 Flutter 실화면 없이 client core에서 기본 API 호출을 검증했다. + - [ ] `KIS Live Data Collection Pipeline`이 완료되어 실제 KIS provider 수집과 worker import/storage/backtest 입력 경계가 검증되었다. - [ ] 화면 wireframe 또는 동등한 화면 정의 산출물이 준비되었고 사용자가 승인했다. ## 범위 @@ -68,6 +69,6 @@ headless 검증과 wireframe 승인을 거친 운영 흐름만 실제 Flutter - 관련 경로: `apps/client/`, `packages/contracts/`, `services/api/` - 표준선(선택): `go_router`는 화면 이동/URL 구조, Riverpod은 API client/socket state/feature state 주입을 담당한다. UI는 `AltSocketClient` provider와 generated/mapped contracts boundary를 통해 API만 바라본다. -- 선행 작업: Flutter Operator Console UX Plan, Operator Headless Workflow Validation, Operator Client API/Core Integration Validation, wireframe 승인 +- 선행 작업: Flutter Operator Console UX Plan, Operator Headless Workflow Validation, Operator Client API/Core Integration Validation, KIS Live Data Collection Pipeline, wireframe 승인 - 후속 작업: Flutter Push Notification Boundary -- 확인 필요: headless 검증은 완료되었고, client API/core 연결 검증과 wireframe 승인 전에는 구현 잠금을 유지한다. +- 확인 필요: headless 검증과 client API/core 연결 검증은 완료되었고, KIS live data collection pipeline과 wireframe 승인 전에는 구현 잠금을 유지한다. diff --git a/agent-roadmap/phase/operator-surface/milestones/kis-live-data-collection-pipeline.md b/agent-roadmap/phase/operator-surface/milestones/kis-live-data-collection-pipeline.md new file mode 100644 index 0000000..55ddf19 --- /dev/null +++ b/agent-roadmap/phase/operator-surface/milestones/kis-live-data-collection-pipeline.md @@ -0,0 +1,80 @@ +# 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로 남긴다. +- 선행 작업: 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