# Milestone: Flutter Operator Console UX Plan

## 위치

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

## 목표

실제 Flutter 화면 구현에 들어가기 전에 operator console의 의미, headless-first 검증 순서, wireframe gate를 고정한다. 이 Milestone의 console은 terminal UI가 아니라 dashboard/control surface지만, 화면 구현은 terminal/YAML 기반 운영 검증과 wireframe 준비가 끝난 뒤로 미룬다.

## 상태

[완료]

## 구현 잠금

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

## 범위

- operator console의 제품 의미와 MVP 범위 정의
- dashboard/control surface가 필요한 이유와 아직 구현하지 않을 화면 범위 정의
- socket connection, backtest, market data의 headless 검증 시나리오 후보
- loading/empty/error/unavailable/disconnected 상태 정책
- 실행 요청 입력, 검증, 실패 응답을 YAML/terminal 결과로 먼저 확인하는 정책
- Riverpod/go_router app shell과 client integration boundary 기준
- 화면 MVP로 넘어가기 위한 wireframe 준비/승인 기준

## 기능

### Epic: [ux-plan] Flutter operator console UX plan

실화면 구현 전에 operator dashboard가 왜 필요한지, 화면 없이 무엇을 먼저 검증할지, 어떤 조건에서 화면 구현 잠금을 풀지 정의한다.

- [x] [scope] Operator console이 terminal UI가 아니라 dashboard/control surface임을 정의하고 MVP 범위와 비범위를 정리한다.
- [x] [headless-first] 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다.
- [x] [state-policy] loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다.
- [x] [boundary] Riverpod/go_router app shell, feature-first 구조, `AltSocketClient`, generated/mapped contracts의 결합 기준을 정리한다.
- [x] [wireframe-gate] 후속 `Flutter Operator Console MVP`의 구현 잠금 해제 조건을 화면 wireframe 준비/승인 여부로 정리한다.
- [x] [validation-handoff] 후속 `Operator Headless Workflow Validation`이 실행할 terminal/YAML 시나리오와 결과 확인 기준을 인수 가능한 형태로 정리한다.

## UX 계획 산출물

### Console 의미와 MVP 범위

- Operator console은 terminal UI가 아니라 API 서버를 control plane으로 삼는 dashboard/control surface다.
- MVP 화면은 market data 상태 조회, backtest run 요청, run 상태 조회, result 요약 조회, connection/disconnected 상태 노출에 한정한다.
- 화면은 operator가 반복적으로 상태를 훑고 실행 요청을 판단하는 표면이며, worker job 구현이나 strategy authoring IDE 역할을 맡지 않는다.
- 비범위는 production charting 전체, mobile app store 배포, push notification, wireframe 없는 layout 확정, worker 직접 제어, 별도 TypeScript web app이다.

### Headless-first 검증 흐름

- 화면 구현 전에 API connection smoke, capability 조회, market data 상태 조회, backtest 실행 요청, run 상태 폴링, result 요약 조회, 실패 응답 표현을 CLI 또는 terminal output으로 확인한다.
- 실행 요청 입력은 YAML scenario로 고정하고, 성공/실패 기대값은 log 또는 test fixture에서 재현 가능해야 한다.
- Flutter 화면은 headless 검증에서 확인된 요청/응답 shape와 상태 전이를 소비한다. 화면이 아직 없는 동안에도 운영 흐름의 입력, 출력, 실패 이유는 terminal에서 읽을 수 있어야 한다.
- 검증 결과는 후속 `Operator Headless Workflow Validation` Milestone이 인수하며, 그 Milestone은 실제 command, fixture, expected output을 확정한다.

### 상태와 action 정책

| 상태 | Headless 표현 기준 | Operator action |
|------|--------------------|-----------------|
| loading | 요청 시작, 응답 대기, run polling 중임을 단계와 함께 출력한다. | 같은 대상 중복 실행은 막고 refresh/cancel 가능 여부만 명시한다. |
| empty | 조회는 성공했지만 market data, run, result가 없는 상태를 출력한다. | import/backtest 실행처럼 다음 생성 action이 있으면 활성화한다. |
| error | 요청 실패, validation 실패, worker 실패를 구분하고 correlation id 또는 run id가 있으면 함께 출력한다. | 입력 수정이나 retry 가능한 action만 허용하고 파괴적 재시도는 요구하지 않는다. |
| unavailable | capability 미지원, worker 미준비, 외부 provider 미설정처럼 현재 환경에서 불가능한 이유를 출력한다. | 해당 action은 비활성화하고 필요한 설정이나 선행 흐름을 안내 가능한 데이터로 남긴다. |
| disconnected | socket 연결 없음, reconnecting, handshake 실패를 구분해 출력한다. | API 의존 action은 비활성화하고 reconnect 또는 diagnostic action만 남긴다. |

### Client boundary

- `go_router`는 operator console의 route와 URL 구조를 소유한다. feature widget은 route path 문자열을 직접 흩뿌리지 않는다.
- Riverpod은 socket client, connection state, feature state, command submission state를 주입한다.
- `AltSocketClient`는 proto-socket connection과 ALT request/response dispatch boundary를 감싼다. Presentation widget은 production endpoint, socket path, generated protobuf detail을 직접 알지 않는다.
- Generated contracts와 mapped view model 사이의 변환은 feature data/application boundary에서 수행한다. Widget은 operator-facing label, status, action availability만 소비한다.
- app shell, provider boundary, generated contract 연결, headless smoke support는 화면 구현 잠금을 깨는 실화면 구현으로 보지 않는다.

### Wireframe gate

- `Flutter Operator Console MVP`의 구현 잠금은 headless validation 결과와 화면 wireframe이 준비된 뒤 해제한다.
- Wireframe은 navigation, market data status panel, backtest request form, run list/detail, result summary, loading/empty/error/unavailable/disconnected 표현을 포함해야 한다.
- Wireframe 승인 전에는 dashboard depth, card layout, chart choice, form flow를 코드로 확정하지 않는다.
- Wireframe은 web/mobile/desktop 단일 UI 표면을 전제로 하되, MVP 승인 기준은 web-first 운영 흐름 확인으로 둔다.

### Headless validation handoff

후속 `Operator Headless Workflow Validation` Milestone은 아래 시나리오를 terminal/YAML 기반으로 구체화한다.

- `api_connection_smoke`: API socket connect, handshake/capability 조회, disconnected/reconnect 실패 표현 확인.
- `market_data_status_query`: symbol/date range 입력으로 market data availability와 empty/unavailable 상태 확인.
- `backtest_run_request`: YAML scenario의 strategy, symbol universe, date range, initial capital 입력 검증과 run 생성 응답 확인.
- `backtest_run_polling`: run id 기반 상태 전이와 실패 사유 표현 확인.
- `backtest_result_summary`: completed run의 summary metrics, empty result, missing run id 에러 확인.
- `invalid_request_matrix`: 필수 입력 누락, 잘못된 symbol/date/capital, 지원하지 않는 capability의 validation 응답 확인.

각 시나리오는 command, input fixture, expected terminal/log output, exit status, 확인할 protobuf/view-model field를 함께 남겨 Flutter MVP가 같은 상태 정책을 소비할 수 있어야 한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-05-31
- 완료 근거: `UX 계획 산출물`에 console scope, headless-first 흐름, 상태 정책, client boundary, wireframe gate, validation handoff가 정리되었고 모든 기능 Task가 체크되었다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 승인에 따라 완료 처리하고 archive로 이동한다. 후속 구현성 작업은 `Operator Headless Workflow Validation`과 `Flutter Operator Console MVP`에서 다룬다.

## 범위 제외

- 실제 Flutter production 화면 구현
- wireframe 없이 dashboard layout, chart, form 흐름을 확정하는 작업
- 별도 TypeScript web app
- 고급 charting 전체
- push notification
- mobile app store 배포 설정

## 작업 컨텍스트

- 관련 경로: `apps/client/`, `packages/contracts/`, `services/api/`
- 표준선(선택): 운영 기능은 화면보다 headless 검증을 먼저 만든다. Flutter는 feature-first 구조를 따르고, `go_router`는 화면 이동과 URL 구조, Riverpod은 API client/socket state/feature state 주입을 담당한다. Presentation widget은 production endpoint나 socket path를 직접 알지 않는다.
- 선행 작업: API-Centered Proto-Socket Rail
- 후속 작업: Operator Headless Workflow Validation, Flutter Operator Console MVP, Flutter Push Notification Boundary
- 확인 필요: 없음
- Workspace 잠금: 관련 lock 없음
- Plan 판단: 현재 Milestone의 기능 Task는 문서형 계획 산출물로 직접 처리했다. 별도 `agent-task` plan이 필요한 코드 구현 또는 headless command 구현은 후속 Milestone 범위다.