alt/agent-roadmap/archive/phase/operator-surface/milestones/flutter-operator-console.md

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가 왜 필요한지, 화면 없이 무엇을 먼저 검증할지, 어떤 조건에서 화면 구현 잠금을 풀지 정의한다.

• [scope] Operator console이 terminal UI가 아니라 dashboard/control surface임을 정의하고 MVP 범위와 비범위를 정리한다.
• [headless-first] 화면 구현 전 CLI, terminal output, YAML scenario, log, test fixture로 검증할 운영 흐름을 정리한다.
• [state-policy] loading/empty/error/unavailable/disconnected 상태와 operator action 가능/불가 정책을 headless 결과 표현 기준으로 정리한다.
• [boundary] Riverpod/go_router app shell, feature-first 구조, AltSocketClient, generated/mapped contracts의 결합 기준을 정리한다.
• [wireframe-gate] 후속 Flutter Operator Console MVP의 구현 잠금 해제 조건을 화면 wireframe 준비/승인 여부로 정리한다.
• [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가 체크되었다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • 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 범위다.