From 1f1cfcabfac0ec0a286b8b5ed83d29b7d66dc538 Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 17 Jun 2026 20:17:09 +0900 Subject: [PATCH] update roadmap and SDD files --- .../backtest-multi-timeframe-coverage.md | 6 +- .../scheduled-market-data-refresh.md | 5 +- .../backtest-multi-timeframe-coverage/SDD.md | 127 ++++++++++++++++++ .../USER_REVIEW.md | 47 +++++++ .../scheduled-market-data-refresh/SDD.md | 121 +++++++++++++++++ .../USER_REVIEW.md | 37 +++++ 6 files changed, 340 insertions(+), 3 deletions(-) create mode 100644 agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md create mode 100644 agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/USER_REVIEW.md create mode 100644 agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md create mode 100644 agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/USER_REVIEW.md diff --git a/agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md b/agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md index 7b52696..f307d89 100644 --- a/agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md +++ b/agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md @@ -26,8 +26,10 @@ - 잠금 해제 조건: 아래 체크리스트 - [ ] SDD 잠금이 해제되어 있다. - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다. + - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다. + - [ ] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다. - 결정 필요: 아래 체크리스트 - - [ ] 분봉 기본 단위를 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 기본 지원할지 결정한다. + - [ ] 분봉 1차 import/backtest 검증 baseline을 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 포함할지 결정한다. - [ ] 월봉을 provider 원천 데이터로 우선 받을지, 일봉에서 deterministic aggregation으로 생성할지 기본 우선순위를 결정한다. ## 범위 @@ -90,4 +92,4 @@ - 표준선(선택): 백테스트는 먼저 단일 timeframe run을 확실히 닫고, 여러 timeframe을 동시에 참조하는 전략은 후속 Milestone으로 미룬다. - 선행 작업: Backtest Data Collection Infrastructure, Backtest Scenario Automation - 후속 작업: Scheduled Market Data Refresh의 multi-timeframe cadence 보강, Multi-Timeframe Strategy Composition 후보 -- 확인 필요: 분봉 기본 단위와 월봉 source-of-truth 우선순위는 SDD에서 사용자 결정으로 확정한다. +- 확인 필요: 분봉 1차 import/backtest 검증 baseline과 월봉 source-of-truth 우선순위는 SDD에서 사용자 결정으로 확정한다. diff --git a/agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md b/agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md index 569c1d4..40ee2d9 100644 --- a/agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md +++ b/agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md @@ -26,7 +26,10 @@ - 잠금 해제 조건: 아래 체크리스트 - [ ] SDD 잠금이 해제되어 있다. - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다. -- 결정 필요: 없음 + - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다. + - [ ] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다. +- 결정 필요: 아래 체크리스트 + - [ ] scheduler를 worker 내장 loop, OS/systemd timer, external cron 중 어디까지 1차 구현으로 둘지 확정한다. ## 범위 diff --git a/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md b/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md new file mode 100644 index 0000000..5b01643 --- /dev/null +++ b/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md @@ -0,0 +1,127 @@ +# SDD: Backtest Multi-Timeframe Coverage + +## 위치 + +- Milestone: `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md` +- Phase: `agent-roadmap/phase/backtest-loop/PHASE.md` + +## 상태 + +[검토중] + +## SDD 잠금 + +- 상태: 잠금 +- 사용자 리뷰: `USER_REVIEW.md` +- 잠금 항목: + - [ ] [D01] 분봉 1차 import/backtest 검증 baseline을 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 포함할지 결정한다. + - [ ] [D02] 월봉의 기본 source of truth를 provider 원천 데이터 우선으로 둘지, 일봉 기반 deterministic aggregation 우선으로 둘지 결정한다. + +## 문제 / 비목표 + +- 문제: ALT의 일봉 MVP 경로는 contracts, domain, storage, CLI scenario, backtest run이 닫혀 있지만 월봉과 분봉은 vocabulary, provider capability, 저장 key, backtest selector, freshness/readiness 의미가 함께 확정되어야 한다. +- 비목표: + - 여러 timeframe을 동시에 참조하는 strategy DSL 또는 factor language 설계 + - tick data, order book, 실시간 streaming bar construction + - Flutter 운영 화면 구현 + - 실거래 order routing 또는 broker execution 변경 + - 외부 provider credential 값이나 개인 secret 문서화 + +## Source of Truth + +| 영역 | 기준 | 메모 | +|------|------|------| +| Roadmap | `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md` | Milestone 목표, 기능 Task, 범위 제외, 완료 후보 반영 기준 | +| Code | `packages/contracts/proto/alt/v1/common.proto` | `Timeframe` enum 원천. 현재 `DAILY`, `MINUTE_1`, `MINUTE_5`가 있으며 월봉 추가가 필요하다. | +| Code | `packages/domain/market/types.go` | domain `market.Timeframe` 원천. 현재 `1d`, `1m`, `5m`가 있다. | +| Code | `packages/contracts/proto/alt/v1/market.proto`, `packages/contracts/proto/alt/v1/backtest.proto` | `Bar`, `ListBarsRequest`, `BacktestRunSpec`의 timeframe 전달 계약 | +| Code | `apps/cli/internal/operator/scenario.go` | scenario string vocabulary와 matrix validation 기준 | +| Code | `services/worker/internal/storage/postgres/queries/queries.sql` | `bars` key는 `(instrument_id, timeframe, timestamp)`이며 timeframe별 독립 저장 기준이다. | +| Code | `services/worker/internal/storage/postgres/migrate_test.go` | `bars` table은 normalized OHLCV 저장 계약을 유지하며 provider raw payload를 섞지 않는다. | +| Code | `services/worker/internal/backtest/bar_source.go` | backtest run selector가 storage에서 timeframe별 bars를 읽는 기준이다. | +| External Provider | KIS | provider capability와 실제 지원 timeframe을 명시적으로 accepted/rejected로 판정해야 한다. | +| User Decision | D01, D02 | 분봉 1차 import/backtest 검증 baseline과 월봉 source of truth 우선순위가 구현 잠금 해제 조건이다. | + +## State Machine + +| 상태 | 진입 조건 | 다음 상태 | 근거 | +|------|-----------|-----------|------| +| `candidate` | monthly/daily/minute timeframe이 scenario 또는 API 입력에 등장한다. | `accepted` 또는 `rejected` | proto/domain/CLI validation, provider capability matrix | +| `rejected` | provider, market, venue, asset type, timeframe 조합이 지원되지 않는다. | terminal | typed error, stable text/JSONL rejected fixture | +| `accepted` | 조합이 capability matrix를 통과한다. | `imported` 또는 `aggregated` | provider import 또는 deterministic aggregation action | +| `imported` | provider 원천 bars가 normalized OHLCV로 저장된다. | `stored` | importer result, `bars` upsert | +| `aggregated` | 일봉 fixture 또는 저장 데이터에서 월봉 OHLCV가 결정적으로 생성된다. | `stored` | aggregation provenance, deterministic monthly fixture | +| `stored` | `bars`가 `(instrument_id, timeframe, timestamp)` key로 저장된다. | `backtest-selectable` 또는 `readiness-checked` | storage query, list bars scenario | +| `backtest-selectable` | `BacktestRunSpec.timeframe`와 selector가 저장 bars를 찾는다. | `backtest-run-terminal` | matrix dry-run, backtest run/result fixture | +| `readiness-checked` | collection freshness가 timeframe별 latest/missing/gap/duplicate를 계산한다. | terminal | CLI text/JSONL freshness output | +| `backtest-run-terminal` | engine이 selected bars로 run을 완료한다. | terminal | deterministic result, run status/result summary | + +## Interface Contract + +- 계약 원문: 없음 +- 입력: + - `Timeframe`: proto enum과 domain value, CLI string의 동일 의미 매핑. `daily`, `minute_1`, `minute_5` 기존 vocabulary는 호환 유지하고 `monthly`를 추가한다. D01은 기존 vocabulary 제거 여부가 아니라 1차 import/backtest 검증 baseline에 `minute_5`까지 포함할지 결정한다. + - `provider_capability`: provider, market, venue, asset type, timeframe별 accepted/rejected와 거부 사유. + - `bar_source`: provider 원천 bars 또는 deterministic aggregation 결과. + - `BacktestRunSpec.timeframe`: backtest matrix와 run selector가 사용할 단일 timeframe. + - `freshness_request`: universe, timeframe, from/to window, expected dates. +- 출력: + - `Bar`: instrument id, timeframe, timestamp, normalized OHLCV. + - `provenance`: 월봉이 provider 원천인지 daily aggregation인지 확인 가능한 근거. 1차 완료 근거는 stable CLI/JSONL 또는 fixture output에 남기고, durable metadata가 필요하면 normalized `bars` key를 깨지 않는 별도 metadata 경계를 둔다. + - `readiness`: timeframe별 latest, missing, gap, duplicate, provider delay 상태. + - `backtest_result`: timeframe별 deterministic run id, status, result summary. +- 금지: + - unsupported provider/timeframe 조합을 daily로 조용히 fallback하지 않는다. + - monthly/daily/minute bars를 같은 query나 result에서 timeframe 구분 없이 섞지 않는다. + - provider raw payload를 `bars` table의 정규화 계약에 섞지 않는다. + - 여러 timeframe을 동시에 참조하는 전략 DSL은 이번 Milestone에서 확정하지 않는다. + +## Acceptance Scenarios + +| ID | Milestone Task | Given | When | Then | +|----|----------------|-------|------|------| +| S01 | `timeframe-vocab` | 기존 `daily`, `minute_1`, `minute_5` vocabulary와 신규 monthly 요구가 있다. | proto/domain/CLI mapping을 검증한다. | monthly가 추가되고 기존 daily/minute compatibility가 유지된다. | +| S02 | `capability-matrix` | KIS KR/US venue와 monthly/daily/minute 후보가 있다. | capability matrix validation을 실행한다. | accepted/rejected case와 거부 사유가 명시적으로 나온다. | +| S03 | `minute-ingest` | 분봉 import 요청 또는 미지원 조합 fixture가 있다. | provider import 또는 reject path를 실행한다. | success 또는 typed rejection이 stable text/JSONL로 남는다. | +| S04 | `monthly-bars` | 동일 daily fixture와 D02 source-of-truth 결정이 있다. | 월봉 provider import 또는 deterministic aggregation을 실행한다. | deterministic monthly OHLCV와 provenance가 남는다. | +| S05 | `store-query` | 동일 instrument의 monthly/daily/minute bars가 있다. | 저장 후 timeframe별 조회를 실행한다. | 각 timeframe이 독립 조회되고 서로 섞이지 않는다. | +| S06 | `run-selector` | monthly/daily/minute scenario matrix가 있다. | dry-run validation과 matrix expand를 실행한다. | timeframe별 run id와 기간 검증 결과가 생성된다. | +| S07 | `fill-policy` | monthly/daily/minute fixture bars와 동일 전략이 있다. | backtest engine fixture를 실행한다. | timeframe별 deterministic result가 나온다. | +| S08 | `freshness-readiness` | monthly/daily/minute freshness fixture가 있다. | collection freshness/readiness scenario를 실행한다. | latest/missing/gap/duplicate 상태가 timeframe별로 구분된다. | + +## Evidence Map + +| Scenario | Required Evidence | `agent-task` 연결 | `Spec Completion` 기대 | +|----------|-------------------|------------------|---------------------------| +| S01 | contracts/domain/CLI mapping test | `agent-task/m-backtest-multi-timeframe-coverage/...` | `timeframe-vocab` task와 monthly 추가 및 기존 daily/minute compatibility test 결과 | +| S02 | capability matrix accepted/rejected tests | `agent-task/m-backtest-multi-timeframe-coverage/...` | `capability-matrix` task와 KIS KR/US case 결과 | +| S03 | minute import success 또는 typed reject fixture | `agent-task/m-backtest-multi-timeframe-coverage/...` | `minute-ingest` task와 stable text/JSONL evidence | +| S04 | deterministic monthly OHLCV fixture와 provenance evidence | `agent-task/m-backtest-multi-timeframe-coverage/...` | `monthly-bars` task와 D02 반영 결과 | +| S05 | storage/query test for `(instrument_id, timeframe, timestamp)` isolation | `agent-task/m-backtest-multi-timeframe-coverage/...` | `store-query` task와 독립 조회 결과 | +| S06 | matrix expand and dry-run validation output | `agent-task/m-backtest-multi-timeframe-coverage/...` | `run-selector` task와 monthly/daily/minute run id evidence | +| S07 | deterministic backtest fixture results | `agent-task/m-backtest-multi-timeframe-coverage/...` | `fill-policy` task와 timeframe별 result evidence | +| S08 | freshness/readiness fixture text/JSONL | `agent-task/m-backtest-multi-timeframe-coverage/...` | `freshness-readiness` task와 timeframe별 latest/missing/gap/duplicate evidence | + +## Cross-repo Dependencies + +- 없음 + +## Drift Check + +- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다. +- [x] Evidence Map이 plan/code-review/complete.log에서 검증 가능하다. +- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다. +- [x] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다. + +## 사용자 리뷰 이력 + +- 없음 + +## 작업 컨텍스트 + +- 표준선: 일봉 MVP 경로는 이미 완료된 기준선이며 multi-timeframe은 기존 daily 경로를 깨지 않고 additive하게 확장한다. +- 표준선: proto-socket과 `packages/contracts/proto`가 ALT runtime 사이의 통신 기준이다. +- 표준선: `services/api`는 얇은 control plane으로 유지하고 provider import, aggregation, backtest execution은 worker 경계에 둔다. +- 표준선: provider가 직접 제공하지 않는 timeframe은 deterministic aggregation 또는 typed rejection 중 하나로만 처리한다. +- 표준선: 백테스트는 먼저 단일 timeframe run을 확실히 닫고 multi-timeframe composition은 후속 Milestone으로 미룬다. +- 후속 SDD: `agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md` diff --git a/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/USER_REVIEW.md b/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/USER_REVIEW.md new file mode 100644 index 0000000..a81dd6c --- /dev/null +++ b/agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/USER_REVIEW.md @@ -0,0 +1,47 @@ +# SDD User Review + +## 상태 + +요청됨 + +## 검토 대상 + +- SDD: `agent-roadmap/sdd/backtest-loop/backtest-multi-timeframe-coverage/SDD.md` +- Milestone: `agent-roadmap/phase/backtest-loop/milestones/backtest-multi-timeframe-coverage.md` + +## 사용자 결정 항목 + +### [D01] 분봉 1차 검증 baseline + +- 결정 필요: 분봉 1차 import/backtest 검증 baseline을 `1m`만으로 시작할지, 기존 vocabulary처럼 `1m`/`5m`를 함께 포함할지 결정한다. +- 추천안: 기존 proto/domain/CLI vocabulary의 `minute_5`는 호환 유지하고, 1차 import/backtest 검증 baseline에는 `1m`/`5m`를 함께 포함한다. provider capability가 실제 지원 여부를 accepted/rejected로 판정하게 한다. +- 대안: 기존 `minute_5` vocabulary는 유지하되, 1차 import/backtest 검증 baseline은 `1m`만 닫고 `5m` provider/backtest fixture는 후속으로 미룬다. +- 영향: scope와 fixture 수가 달라진다. `1m`/`5m`를 함께 검증하면 기존 vocabulary와 더 잘 맞지만 provider별 reject case를 더 명시해야 한다. `1m`만 닫아도 기존 `minute_5` mapping은 제거하지 않는다. +- 적용 위치: + - SDD: `SDD 잠금`, `Interface Contract`, `Acceptance Scenarios` + - Milestone: `구현 잠금`, `timeframe-vocab`, `minute-ingest` + +### [D02] 월봉 source of truth 우선순위 + +- 결정 필요: 월봉을 provider 원천 데이터로 우선 받을지, 일봉에서 deterministic aggregation으로 생성할지 기본 우선순위를 결정한다. +- 추천안: 1차 구현은 일봉 기반 deterministic aggregation을 기본 source of truth로 두고, provider 월봉은 capability가 확인될 때 후속 또는 provider-specific path로 추가한다. +- 대안: provider 월봉 원천 데이터를 우선하고 일봉 aggregation은 fallback으로 둔다. +- 영향: provider 의존도와 검증 방식이 달라진다. deterministic aggregation 우선은 현재 daily MVP와 fixture를 재사용하기 쉬운 대신 provenance를 반드시 남겨야 한다. +- 적용 위치: + - SDD: `Source of Truth`, `State Machine`, `Interface Contract`, `Acceptance Scenarios` + - Milestone: `구현 잠금`, `monthly-bars` + +## 승인 항목 + +- [ ] 위 결정 항목을 승인했다. +- [ ] SDD 잠금 해제를 승인했다. + +## 답변 기록 + +- 없음 + +## 해결 조건 + +- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다. +- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다. +- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다. diff --git a/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md b/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md new file mode 100644 index 0000000..4e27a81 --- /dev/null +++ b/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md @@ -0,0 +1,121 @@ +# SDD: Scheduled Market Data Refresh + +## 위치 + +- Milestone: `agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md` +- Phase: `agent-roadmap/phase/backtest-loop/PHASE.md` + +## 상태 + +[검토중] + +## SDD 잠금 + +- 상태: 잠금 +- 사용자 리뷰: `USER_REVIEW.md` +- 잠금 항목: + - [ ] [D01] scheduler를 worker 내장 loop, OS/systemd timer, external cron 중 어디까지 1차 구현으로 둘지 확정한다. + +## 문제 / 비목표 + +- 문제: market data import가 수동 scenario 실행에만 의존하면 원격 서버의 backtest input freshness를 반복 확인하기 어렵다. scheduler는 provider 호출, DB upsert, retry/backfill, freshness/readiness, remote smoke까지 같은 운영 경계로 묶어야 한다. +- 비목표: + - Flutter 운영 화면 구현 + - 새 strategy 판단 로직 또는 투자 의사결정 알고리즘 설계 + - paper/live order routing과 실거래 adapter 변경 + - 월봉/분봉 provider import와 backtest engine 지원 확장 전체 + - 외부 provider credential 값이나 개인 secret 문서화 + +## Source of Truth + +| 영역 | 기준 | 메모 | +|------|------|------| +| Roadmap | `agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md` | Milestone 목표, 기능 Task, 범위 제외, 완료 후보 반영 기준 | +| Code | `services/worker/cmd/alt-worker/main.go` | worker runtime wiring과 job runner 등록 기준 | +| Code | `services/worker/internal/config/config.go` | worker runtime env/config source of truth. scheduler config는 secret 값을 직접 보관하지 않는다. | +| Code | `services/worker/internal/jobs/marketdata_jobs.go` | `import_daily_bars` job payload, provider capability gate, importer dispatch 기준 | +| Code | `services/worker/internal/storage/postgres/queries/queries.sql` | `bars` upsert idempotency 기준 | +| Code | `apps/cli/internal/operator/scenario.go` | scenario validation, `collection_freshness`, matrix/readiness smoke 기준 | +| Code | `apps/cli/testdata/operator/headless_validation.md` | operator-facing headless evidence key와 scenario handoff 기준 | +| External Provider | KIS | scheduled tick이 호출할 provider이며 delay, gap, missing, typed error를 상태로 남겨야 한다. | +| User Decision | D01 | scheduler 실행 주체와 운영 책임 경계가 구현 잠금 해제 조건이다. | + +## State Machine + +| 상태 | 진입 조건 | 다음 상태 | 근거 | +|------|-----------|-----------|------| +| `config-candidate` | schedule config가 named universe, provider, selector, timeframe, cadence, timezone, backfill window를 선언한다. | `config-valid` 또는 `config-rejected` | validate/dry-run output | +| `config-rejected` | 필수 필드 누락 또는 provider/timeframe 조합 미지원이다. | terminal | typed validation error, stable text/JSONL | +| `config-valid` | schedule config가 validation을 통과한다. | `scheduled` | next window calculation | +| `scheduled` | tick 시간이 도래하거나 manual tick smoke가 실행된다. | `running` 또는 `skipped` | scheduler log/status | +| `skipped` | 동일 tick이 이미 running이거나 lock/idempotency guard가 막는다. | terminal | duplicate tick evidence | +| `running` | import job이 provider와 DB upsert를 실행한다. | `succeeded`, `stale`, 또는 `failed` | job result, importer result, DB state | +| `succeeded` | import와 freshness/readiness가 expected window를 만족한다. | `ready-for-backtest` | status JSONL, freshness output | +| `stale` | provider delay, missing, gap이 남아 backfill/retry가 필요하다. | `scheduled` 또는 terminal | retry/backfill calculation, stale status | +| `failed` | provider, config, DB, runtime 오류가 발생한다. | `scheduled` 또는 terminal | last_error, error status | +| `ready-for-backtest` | scheduler가 적재한 데이터로 selector가 bars를 찾는다. | terminal | backtest matrix/result smoke exit code `0` | + +## Interface Contract + +- 계약 원문: 없음 +- 입력: + - `schedule_config`: named universe별 provider, selector, timeframe, cadence, timezone, backfill window. + - `tick`: scheduled 또는 manual smoke로 실행되는 refresh trigger. + - `provider_capability`: provider, market, venue, timeframe별 accepted/rejected 판정. + - `runtime_env`: provider credential과 DB URL은 config 파일에 쓰지 않고 원격 runtime env/SOPS 주입 경계에서 제공한다. + - `freshness_window`: latest, expected dates, missing/gap/duplicate/provider delay를 계산할 기간. +- 출력: + - `refresh_status`: last_success, last_error, next_run, imported bar count, missing/gap/duplicate/provider_delay. + - `job_result`: import job success/stale/error와 retry/backfill decision. + - `readiness`: backtest selector가 scheduled import 결과를 사용할 수 있는지에 대한 headless result. + - `remote_smoke`: migration, runtime startup, tick, freshness query, backtest selector/result scenario exit code. +- 금지: + - schedule config에 secret 값을 저장하지 않는다. + - 동일 tick 재실행이 duplicate `bars` row를 만들지 않는다. + - provider delay나 gap을 성공으로 조용히 숨기지 않는다. + - scheduler가 Flutter 화면 구현을 전제하지 않는다. + - 월봉/분봉 import 확장은 이 Milestone에서 새로 확정하지 않고 지원되는 timeframe만 대상으로 삼는다. + +## Acceptance Scenarios + +| ID | Milestone Task | Given | When | Then | +|----|----------------|-------|------|------| +| S01 | `schedule-config` | named universe별 provider, selector, timeframe, cadence, timezone, backfill window가 있다. | validate/dry-run을 실행한다. | next window와 rejected combination이 text/JSONL로 출력된다. | +| S02 | `scheduled-runner` | 원격 runtime과 idempotent `bars` upsert가 있다. | scheduler tick을 2회 실행한다. | duplicate row 없이 freshness/readiness output이 남는다. | +| S03 | `retry-backfill` | provider delay, missing, gap fixture가 있다. | retry/backfill calculation을 실행한다. | stale/error 상태와 backfill window가 stable text/JSONL로 구분된다. | +| S04 | `refresh-status` | success, stale, error 상태가 있다. | status scenario를 실행한다. | last_success, last_error, next_run, bar count, missing/gap/duplicate/provider_delay가 구분된다. | +| S05 | `backtest-readiness` | scheduler tick이 bars를 적재했다. | remote runner에서 backtest matrix 또는 result summary scenario를 실행한다. | exit code `0`과 result/readiness evidence가 남는다. | + +## Evidence Map + +| Scenario | Required Evidence | `agent-task` 연결 | `Spec Completion` 기대 | +|----------|-------------------|------------------|---------------------------| +| S01 | schedule config validate test와 dry-run text/JSONL | `agent-task/m-scheduled-market-data-refresh/...` | `schedule-config` task와 next window/rejected combination evidence | +| S02 | duplicate tick smoke, `bars` key 중복 없음, freshness/readiness output | `agent-task/m-scheduled-market-data-refresh/...` | `scheduled-runner` task와 2회 tick idempotency evidence | +| S03 | missing/gap/provider delay fixture 또는 local smoke | `agent-task/m-scheduled-market-data-refresh/...` | `retry-backfill` task와 stale/error/backfill evidence | +| S04 | success/stale/error status scenario expected JSONL | `agent-task/m-scheduled-market-data-refresh/...` | `refresh-status` task와 status field evidence | +| S05 | remote runner smoke after scheduler tick | `agent-task/m-scheduled-market-data-refresh/...` | `backtest-readiness` task와 exit code `0` evidence | + +## Cross-repo Dependencies + +- 없음 + +## Drift Check + +- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다. +- [x] Evidence Map이 plan/code-review/complete.log에서 검증 가능하다. +- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다. +- [x] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다. + +## 사용자 리뷰 이력 + +- 없음 + +## 작업 컨텍스트 + +- 표준선: 운영 기능은 먼저 화면 없이 CLI, YAML scenario, JSONL/text output, fixture, remote smoke로 검증한다. +- 표준선: scheduled import는 provider 호출과 DB upsert를 idempotent하게 유지하고 동일 tick 재실행이 중복 row를 만들지 않아야 한다. +- 표준선: `services/worker`가 데이터 수집, 정규화, backtest, scheduled job처럼 오래 걸리거나 비동기적인 일을 담당한다. +- 표준선: scheduler config에는 secret 값을 넣지 않고 원격 runtime env/SOPS 주입 경계를 따른다. +- 표준선: `services/api`는 client-facing 요청을 worker 실행/조회 경계로 중계하는 control plane으로 남긴다. +- 후속 SDD: 없음 diff --git a/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/USER_REVIEW.md b/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/USER_REVIEW.md new file mode 100644 index 0000000..83a45ee --- /dev/null +++ b/agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/USER_REVIEW.md @@ -0,0 +1,37 @@ +# SDD User Review + +## 상태 + +요청됨 + +## 검토 대상 + +- SDD: `agent-roadmap/sdd/backtest-loop/scheduled-market-data-refresh/SDD.md` +- Milestone: `agent-roadmap/phase/backtest-loop/milestones/scheduled-market-data-refresh.md` + +## 사용자 결정 항목 + +### [D01] scheduler 실행 주체 + +- 결정 필요: scheduler를 worker 내장 loop, OS/systemd timer, external cron 중 어디까지 1차 구현으로 둘지 확정한다. +- 추천안: 1차 구현은 `services/worker` 내장 scheduler loop로 두고, OS/systemd는 worker process supervision까지만 맡긴다. external cron은 후속 운영 옵션으로 남긴다. +- 대안: systemd timer 또는 external cron이 CLI/manual tick을 호출하고 worker는 import/readiness action만 수행한다. +- 영향: 운영 책임 경계와 failure surface가 달라진다. worker 내장 loop는 ALT runtime 내부에서 status, retry, idempotency를 한곳에 모으기 쉽고, cron 방식은 process lifecycle과 schedule state가 외부로 분산된다. +- 적용 위치: + - SDD: `SDD 잠금`, `State Machine`, `Interface Contract` + - Milestone: `구현 잠금`, `schedule-config`, `scheduled-runner` + +## 승인 항목 + +- [ ] 위 결정 항목을 승인했다. +- [ ] SDD 잠금 해제를 승인했다. + +## 답변 기록 + +- 없음 + +## 해결 조건 + +- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다. +- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다. +- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.