# Milestone: Operator Client API/Core Integration Validation

## 위치

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

## 목표

Flutter 실화면 구현 전에 client core, provider, repository 경계에서 API socket 연결과 기본 ALT API 호출이 안정적으로 동작하는지 검증한다. 화면 layout, dashboard depth, chart, form visual design은 뒤로 미루고, generated/mapped contracts와 proto-socket client layer가 market data와 backtest API를 호출하고 typed result/error를 받을 수 있음을 먼저 확인한다.

## 상태

[완료]

## 구현 잠금

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

## 범위

- Flutter client의 화면 없는 API connection/bootstrap 경계
- generated/mapped contracts 기반 request/response mapping
- API socket connect/disconnect/timeout 상태를 core state로 표현
- market data status/list 계열 기본 호출 검증
- backtest list/detail/result/start 계열 기본 호출 검증
- unavailable/error/disconnected/typed `ErrorInfo` mapping 검증
- UI 구현으로 넘길 API/core readiness evidence 정리

## 기능

### Epic: [client-api-core] Client API/core integration validation

운영 화면을 만들기 전에 Flutter client 내부의 API 연결과 기본 호출 경계를 화면 없이 검증한다.

- [x] [client-contracts] generated/mapped contracts를 client core에서 사용할 수 있게 정리한다. 검증: Flutter/Dart test가 request/response mapping을 확인한다.
- [x] [socket-core] API socket 연결, 해제, timeout 상태를 화면 없는 client state로 표현한다. 검증: fake 또는 local socket 기반 test가 상태 전이를 확인한다.
- [x] [market-call] market data status/list 기본 API 호출을 client core에서 수행할 수 있다. 검증: test가 request payload와 parsed result/status key를 확인한다.
- [x] [backtest-call] backtest list/detail/result/start 기본 API 호출을 client core에서 수행할 수 있다. 검증: test가 success result와 typed error mapping을 확인한다.
- [x] [error-core] unavailable/error/disconnected 상태가 UI copy가 아닌 안정적인 client state로 남는다. 검증: typed error와 transport failure unit test가 통과한다.
- [x] [handoff] Flutter Operator Console MVP로 넘길 API/core readiness evidence를 정리한다. 검증: 실행 명령, fixture/fake, 기대 상태, 남은 wireframe 의존성을 문서화한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-02
- 완료 근거: `01_contract_mapping`, `02+01_socket_state`, `03+01_market_repository`, `04+02,03_backtest_error` 완료 로그가 `client-contracts`, `socket-core`, `market-call`, `backtest-call`, `error-core` Task의 PASS evidence를 남겼고, 아래 handoff evidence에 Flutter Operator Console MVP로 넘길 실행 명령/fixture/기대 상태/남은 wireframe 의존성을 정리했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 요청으로 현재 마일스톤을 완료 처리하고 archive 이동한다.

## 범위 제외

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

## 작업 컨텍스트

- 관련 경로: `apps/client/`, `packages/contracts/`, `services/api/`, `apps/cli/testdata/operator/`
- 표준선(선택): 화면 구현 없이 Riverpod/provider 또는 repository 수준에서 API client boundary를 먼저 안정화한다. 검증은 fake/local socket, fixture, Dart/Flutter test, grep 가능한 output 중 가장 작은 충분한 방식으로 남긴다.
- 선행 작업: Flutter Operator Console UX Plan, Operator Headless Workflow Validation
- 후속 작업: Flutter Operator Console MVP
- 확인 필요: 없음

## API/Core Readiness Handoff

- 실행 명령:
  - `cd apps/client && flutter test test/contracts/alt_api_result_test.dart`
  - `cd apps/client && flutter test test/integrations/socket/socket_connection_controller_test.dart`
  - `cd apps/client && flutter test test/features/market/market_repository_test.dart`
  - `cd apps/client && flutter test test/features/backtest/backtest_repository_test.dart`
  - `cd apps/client && flutter test`
- fixture/fake:
  - contract mapping은 generated protobuf response의 populated/unset `ErrorInfo`와 unsupported response type을 unit test fixture로 사용한다.
  - socket state는 fake/local socket controller transition test로 connect, handshake, timeout, explicit disconnect, socket close callback 상태를 확인한다.
  - market/backtest repository는 fake `WebSocket`과 `PacketBase` round trip으로 request payload, decoded success response, typed `ErrorInfo`, timeout, decode failure, disconnected 상태를 확인한다.
- 기대 상태:
  - client core는 UI copy 없이 `AltApiResult`, `AltApiError`, `AltTransportKind`, `SocketConnectionState`로 success/error/transport state를 보존한다.
  - `MarketRepository`는 `listInstruments`, `listBars`를 `AltApiResult`로 반환한다.
  - `BacktestRepository`는 `listBacktestRuns`, `getBacktestRunDetail`, `getBacktestResult`, `startBacktest`를 `AltApiResult`로 반환한다.
- 남은 wireframe 의존성:
  - Flutter Operator Console MVP 화면 구성, dashboard depth, chart/form visual design, navigation 확정은 이 마일스톤 범위 밖이며 wireframe 승인 뒤 후속 마일스톤에서 처리한다.
