# Milestone: Command-First Operator Workflow

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/operator-surface/PHASE.md`

## 목표

Flutter 실화면을 보류한 상태에서 KIS live data, worker storage, market status, backtest 실행/결과 확인을 CLI/YAML/로그 중심의 반복 가능한 operator workflow로 묶는다. 화면에 올릴 기능이 충분히 표면화될 때까지 command-first 운영을 기본 경로로 유지하고, 나중에 UI MVP가 가져갈 contract와 evidence key를 축적한다.

## 상태

[계획]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- KIS paper/real daily smoke와 provider readiness command handoff
- KIS live daily import를 worker storage까지 연결하는 command 또는 scenario 경계
- storage 기반 market data status 조회 command/YAML scenario
- imported daily bars를 사용한 backtest start/poll/result command workflow
- command output의 machine-readable status/evidence key 정리
- UI MVP로 넘길 operator workflow handoff 갱신

## 기능

### Epic: [cmd-operator] Command-first operator workflow

화면 없이도 운영자가 KIS 데이터 수집, 상태 조회, 백테스트 실행/결과 확인을 반복할 수 있는 command path를 만든다.

- [ ] [kis-smoke-runbook] KIS paper/real daily smoke와 Go live-provider smoke 실행 경로가 command runbook으로 정리되어 있다. 검증: secret 원문 없이 readiness/smoke/evidence key가 문서화되고 smoke command가 dry failure와 live-gated success 경로를 구분한다.
- [ ] [live-import-command] KIS live daily bars를 worker storage에 import하는 command 또는 YAML scenario가 있다. 검증: fake/provider test와 필요한 integration smoke가 import result와 storage upsert를 확인한다.
- [ ] [market-status-scenario] imported market data를 CLI/YAML로 조회할 수 있다. 검증: `alt operator scenario validate/run` 또는 동등한 command가 instrument/bar count와 typed unavailable/error key를 출력한다.
- [ ] [backtest-command-flow] imported daily bars를 입력으로 backtest start/poll/result를 command workflow에서 확인할 수 있다. 검증: start/poll/result scenario가 run id, terminal status, result summary key를 출력한다.
- [ ] [operator-handoff] command-first workflow가 UI MVP로 넘길 화면 후보와 아직 화면으로 올리지 않을 항목을 분리한다. 검증: handoff 문서가 command, expected output key, 반복 운영 여부, UI defer 사유를 함께 기록하고, 충분히 표면화되지 않은 기능은 화면 후보에서 제외한다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 아직 기능 Task와 검증이 충족되지 않았다.
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- Flutter 실화면 구현
- wireframe 확정
- push notification
- paper trading 주문/포지션 모델
- 실거래 주문 API
- production 자동 수집 스케줄링
- secret 원문, 계좌번호, token의 tracked 문서 기록

## 작업 컨텍스트

- 관련 경로: `apps/cli/`, `apps/cli/testdata/operator/`, `bin/`, `services/api/`, `services/worker/`, `docs/`
- 표준선(선택): 현재 운영은 화면보다 CLI/YAML/log/test fixture를 우선한다. Flutter MVP는 command workflow에서 반복 운영 항목, 상태 key, 우선순위가 충분히 표면화되어 정리 가능한 뒤에 다시 연다.
- 표준선(선택): command output은 사람이 읽을 수 있으면서도 `jsonl`/status key처럼 script가 grep 가능한 형태를 유지한다.
- 표준선(선택): KIS secret은 SOPS + age command-lifetime env 주입 경계만 사용하고 tracked 문서에는 sanitized evidence만 남긴다.
- 선행 작업: Operator Headless Workflow Validation, Operator Client API/Core Integration Validation, KIS Live Data Collection Pipeline
- 후속 작업: Paper Trading Readiness, Paper Trading Command Workflow, US Market Expansion, Live Trading Boundary, Flutter Operator Console MVP
- 확인 필요: 없음