# Milestone: Paper Trading Command Workflow

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/trading-expansion/PHASE.md`

## 목표

`Paper Trading Readiness`에서 정의한 paper account, virtual order/fill, position, risk guard를 Flutter 화면 없이 CLI/YAML/log 중심의 반복 가능한 command workflow로 검증한다. paper trading 기능이 충분히 표면화되고 운영자가 어떤 상태와 액션을 반복해서 보는지 정리된 뒤에만 UI 후보로 넘긴다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음
- 결정 내용:
  - [x] `Paper Trading Readiness`가 완료되어 paper account/order/fill/position/risk 경계가 준비되었다.
  - [x] 첫 paper trading scenario는 status 조회 우선으로 시작한다.

## 범위

- paper account/portfolio 상태 조회 command
- virtual order submit/cancel/fill simulation command 또는 YAML scenario
- position/risk guard 상태 조회 command
- paper execution loop smoke
- paper trading command output의 machine-readable status/evidence key 정리
- UI MVP로 넘길 paper trading 화면 후보와 보류 항목 분리

## 기능

### Epic: [paper-cmd] Paper trading command workflow

paper trading을 화면 없이 반복 검증하고, 나중에 UI로 올릴 운영 항목을 command evidence로 먼저 정리한다.

- [x] [paper-status-command] paper account, portfolio, position 상태를 command로 조회할 수 있다. 검증: status command 또는 scenario가 account_id, cash, position_count, risk key를 출력한다.
- [x] [paper-order-command] virtual order submit/cancel/fill simulation을 command로 실행할 수 있다. 검증: order lifecycle scenario가 order id, status transition, fill summary를 출력한다.
- [x] [paper-risk-command] 최소 risk guard 결과를 command workflow에서 확인할 수 있다. 검증: 허용/차단 case가 typed status/error key로 구분된다.
- [x] [paper-loop-smoke] paper execution loop를 fixture 또는 fake market data로 smoke 실행할 수 있다. 검증: loop command가 run id, terminal status, position/equity summary를 출력한다.
- [x] [paper-ui-handoff] paper trading에서 화면에 올릴 후보와 아직 command로만 둘 항목을 분리한다. 검증: handoff 문서가 command, expected output key, 반복 운영 여부, UI defer 사유를 기록한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-06
- 완료 근거:
  - 모든 기능 Task가 완료 로그의 `Roadmap Completion` Task id와 매칭되어 `[x]`로 동기화되었다.
  - `paper-order-command`는 `agent-task/archive/2026/06/m-paper-trading-command-workflow/03+02_order_lifecycle/complete.log` 기준 PASS다.
  - `paper-ui-handoff`는 `agent-task/archive/2026/06/m-paper-trading-command-workflow/04+01,02,03_ui_handoff/complete.log` 기준 PASS다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 요청으로 현 마일스톤을 완료 처리하고 archive로 이동한다.

## 범위 제외

- Flutter 실화면 구현
- 실거래 주문 제출
- broker 계좌 잔고 실시간 동기화
- 고급 리스크 엔진
- production 자동 execution

## 작업 컨텍스트

- 관련 경로: `apps/cli/`, `apps/cli/testdata/operator/`, `services/worker/`, `services/api/`, `packages/domain/`
- 표준선(선택): paper trading은 실거래 전 검증 경계이며, 먼저 command workflow로 반복 운영성과 상태 key를 확인한다.
- 표준선(선택): UI는 command workflow에서 반복되는 status/action/evidence key가 정리된 뒤에만 후보로 올린다.
- 현재 작업: 사용자 완료 승인에 따라 archive 이동까지 완료됐다.
- 직접 처리 완료:
  - [x] `paper-status-command`: status output에 `account_id`, `cash`, `position_count`, `risk` key를 고정했고 2026-06-05 local `bin/test`가 통과했다.
  - [x] `paper-loop-smoke`: `agent-task/archive/2026/06/m-paper-trading-command-workflow/01_loop_smoke/complete.log` 기준 PASS. 검증: `go test -count=1 ./apps/cli/internal/operator`, `PATH="/tmp/protoc293/bin:$PATH" bin/test`.
  - [x] `paper-risk-command`: `agent-task/archive/2026/06/m-paper-trading-command-workflow/02+01_risk_command/complete.log` 기준 PASS. 검증: `PATH="/tmp/protoc293/bin:$PATH" bin/contracts-check`, `go test ./services/worker/...`, `go test ./services/api/...`, `go test ./apps/cli/internal/operator`, `PATH="/tmp/protoc293/bin:$PATH" bin/test`.
  - [x] `paper-order-command`: `agent-task/archive/2026/06/m-paper-trading-command-workflow/03+02_order_lifecycle/complete.log` 기준 PASS. 검증: `go test -count=1 ./services/worker/internal/papertrading ./services/worker/internal/socket`, `go test -count=1 ./apps/cli/internal/operator`, `PATH="/tmp/protoc293/bin:$PATH" bin/test`.
  - [x] `paper-ui-handoff`: `agent-task/archive/2026/06/m-paper-trading-command-workflow/04+01,02,03_ui_handoff/complete.log` 기준 PASS. 검증: `go test -count=1 ./apps/cli/internal/operator`, `bin/test`, `git diff --check`.
- 큰 작업 plan:
  - 완료: `agent-task/archive/2026/06/m-paper-trading-command-workflow/01_loop_smoke/complete.log`
  - 완료: `agent-task/archive/2026/06/m-paper-trading-command-workflow/02+01_risk_command/complete.log`
  - 완료: `agent-task/archive/2026/06/m-paper-trading-command-workflow/03+02_order_lifecycle/complete.log`
  - 완료: `agent-task/archive/2026/06/m-paper-trading-command-workflow/04+01,02,03_ui_handoff/complete.log`
- 진행 순서:
  1. status 조회 scenario로 account_id, cash, position_count, risk key를 고정한다.
  2. paper execution loop smoke로 run id, terminal status, position/equity summary를 확인한다.
  3. risk guard 조회/판정 case를 typed status/error key로 분리한다.
  4. virtual order lifecycle은 submit/cancel/fill simulation command 또는 YAML scenario로 확장한다.
  5. 반복 운영 key와 UI defer 사유를 handoff 문서로 정리한다.
- 선행 작업: Paper Trading Readiness
- 후속 작업: US Market Expansion, Live Trading Boundary, Flutter Operator Console MVP
- 확인 필요: 없음
