# Milestone: Operator Headless Workflow Validation

## 위치

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

## 목표

Flutter 화면 없이 ALT 운영 흐름을 terminal/YAML/log/test fixture 기반으로 먼저 검증한다. market data와 backtest 조회/실행 경로가 화면 없이도 구성, 실행, 결과 확인이 가능해진 뒤에만 operator dashboard 화면 구현 후보로 넘긴다.

## 상태

[완료]

## 구현 잠금

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

## 범위

- YAML 또는 동등한 파일 기반 operator scenario 정의
- CLI/terminal entrypoint에서 scenario 실행 또는 조회
- market data status/import 결과 확인
- backtest list/detail/result/start 요청 결과 확인
- unavailable/error/disconnected 결과의 machine-readable 또는 grep 가능한 출력
- 화면 구현 전 검증 evidence 산출 방식
- `api_connection_smoke`, `market_data_status_query`, `backtest_run_request`, `backtest_run_polling`, `backtest_result_summary`, `invalid_request_matrix` 시나리오의 command/input/output/exit code 기준 확정

## 기능

### Epic: [headless-op] Headless operator workflow validation

운영 화면을 만들기 전에 같은 API/worker 경계를 화면 없이 검증한다.

- [x] [scenario-format] operator scenario를 YAML 또는 동등한 파일 형식으로 표현한다. 검증: 예시 scenario가 parser 또는 dry-run 검증을 통과한다.
- [x] [terminal-run] terminal에서 scenario를 실행하거나 대표 조회를 수행할 수 있다. 검증: CLI 또는 script가 exit code와 요약 출력을 남긴다.
- [x] [market-check] market data status/import 관련 결과를 화면 없이 확인할 수 있다. 검증: fixture 또는 local smoke가 상태 출력을 확인한다.
- [x] [backtest-check] backtest list/detail/result/start 관련 결과를 화면 없이 확인할 수 있다. 검증: fixture 또는 local smoke가 성공/실패 결과를 확인한다.
- [x] [error-output] unavailable/error/disconnected 상태가 화면 없이도 판별 가능한 출력으로 남는다. 검증: typed error 또는 상태 코드 출력 테스트가 통과한다.
- [x] [handoff] Flutter 화면 MVP로 넘길 수 있는 검증 evidence와 남은 wireframe 의존성을 정리한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-01
- 완료 근거: `apps/cli/internal/operator/scenario.go`, `apps/cli/internal/cli/cli.go`, `apps/cli/internal/operator/runner.go`가 YAML scenario validate/run과 text/jsonl 출력을 제공한다.
- 완료 근거: `apps/cli/testdata/operator/*.yaml`, `apps/cli/testdata/operator/expected/*.jsonl`, `apps/cli/testdata/operator/headless_validation.md`가 market data, backtest, invalid request matrix의 command/input/output/exit code evidence를 정리한다.
- 완료 근거: 원격 ALT checkout에서 `go test ./apps/cli/...`가 통과했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-01 사용자 요청으로 완료 승인 및 archive 이동을 수행했다. `bin/test` 전체 smoke는 원격 checkout에서 `protoc-gen-go` 미설치로 차단되었으며, 필요하면 원격 toolchain 보강 후 재실행한다.

## 범위 제외

- Flutter 실화면 구현
- dashboard layout, chart, form visual design 확정
- push notification
- production 운영 자동화

## 작업 컨텍스트

- 관련 경로: `apps/cli/`, `bin/`, `services/api/`, `services/worker/`, `packages/contracts/`
- 표준선(선택): 화면 구현보다 CLI/YAML/headless smoke를 먼저 만들고, 결과는 exit code와 machine-readable 또는 grep 가능한 출력으로 남긴다.
- 선행 작업: Flutter Operator Console UX Plan
- 후속 작업: Flutter Operator Console MVP
- 확인 필요: 없음

## UX Plan handoff 기준

`Flutter Operator Console UX Plan`에서 넘기는 headless validation 후보는 다음 실행 단위로 구체화한다.

| Scenario | 입력 | 확인 결과 |
|----------|------|-----------|
| `api_connection_smoke` | API socket host/path와 optional reconnect 설정 | handshake/capability, disconnected/reconnect 실패, exit code |
| `market_data_status_query` | symbol, date range, provider/capability option | availability, empty, unavailable 상태와 grep 가능한 status key |
| `backtest_run_request` | strategy, symbol universe, date range, initial capital | validation success/failure, run id, typed error key |
| `backtest_run_polling` | run id, polling timeout | queued/running/completed/failed 전이와 실패 사유 |
| `backtest_result_summary` | completed run id | summary metrics, empty result, missing run id error |
| `invalid_request_matrix` | 필수 입력 누락 또는 잘못된 symbol/date/capital/capability | validation error, unavailable/error 구분, non-zero exit code |

각 scenario는 command, YAML 또는 동등 fixture, expected terminal/log output, exit code, 확인할 protobuf 또는 view-model field를 evidence로 남긴다.