<!-- task=m-api-centered-proto-socket-rail/03+01_client_api_wrappers plan=0 tag=CLIENT -->
# PLAN-cloud-G07: Flutter Client API Proto-Socket Wrappers

## 이 파일을 읽는 구현 에이전트에게
이 계획은 Flutter client가 API 서버만 바라보는 proto-socket wrapper를 완성하는 작업이다. worker나 DB, Redis, 별도 HTTP runtime으로 우회하지 않는다.

## 배경
`AltSocketClient`는 `apps/client/lib/src/integrations/socket/alt_socket_client.dart:9`에서 proto-socket client를 감싸고 hello/listBacktestRuns/getBacktestRunDetail/getBacktestResult/compareBacktestRuns를 제공한다. 하지만 contracts에는 `StartBacktestRequest`, `ListInstrumentsRequest`, `ListBarsRequest`가 있고 client wrapper에는 아직 빠져 있다. UI는 socket state를 표시하지만 API 작업 surface가 충분히 열려 있지 않다.

## 사용자 리뷰 요청 흐름
client에서 worker 직접 연결이나 API 외 runtime endpoint가 필요하다는 요구가 나오면 중단하고 사용자 리뷰 요청을 남긴다. 프로젝트 룰상 client는 API만 바라봐야 한다.

## 분석 결과
### 읽은 파일
- `apps/client/lib/src/integrations/socket/alt_socket_client.dart`
- `apps/client/lib/src/integrations/socket/socket_endpoint.dart`
- `apps/client/lib/src/integrations/socket/socket_connection_controller.dart`
- `apps/client/lib/src/contracts/alt_contracts.dart`
- `apps/client/test/integrations/socket/alt_socket_client_test.dart`
- `apps/client/test/contracts/alt_contracts_test.dart`
- `apps/client/integration_test/socket_runtime_smoke_test.dart`
- `apps/client/test_runtime/socket_web_runtime_smoke_test.dart`
- `packages/contracts/proto/alt/v1/backtest.proto`
- `packages/contracts/proto/alt/v1/market.proto`
- `../proto-socket/dart/lib/src/communicator.dart`

### 테스트 커버리지 공백
- client wrapper test는 일부 backtest 조회 요청만 확인한다.
- start backtest, market instruments/bars request wrapper coverage가 없다.
- 실제 runtime smoke는 원격/허용된 환경에서만 돌려야 한다.

### 심볼 참조
- `AltSocketClient`: `apps/client/lib/src/integrations/socket/alt_socket_client.dart:9`
- `connect`: `apps/client/lib/src/integrations/socket/alt_socket_client.dart:16`
- `hello`: `apps/client/lib/src/integrations/socket/alt_socket_client.dart:33`
- `listBacktestRuns`: `apps/client/lib/src/integrations/socket/alt_socket_client.dart:43`
- `getBacktestRunDetail`: `apps/client/lib/src/integrations/socket/alt_socket_client.dart:53`
- `getBacktestResult`: `apps/client/lib/src/integrations/socket/alt_socket_client.dart:64`
- `compareBacktestRuns`: `apps/client/lib/src/integrations/socket/alt_socket_client.dart:74`
- Dart proto-socket `sendRequest`: `../proto-socket/dart/lib/src/communicator.dart`

### 분할 판단
이 작업은 client wrapper와 tests만 다룬다. API가 실제 domain 응답을 worker에서 받아오는 구현은 `04+02_backtest_rail`, `05+02_market_rail`의 책임이다.

### 범위 결정 근거
- client 입장에서는 API proto-socket method surface가 먼저 안정화되어야 UI 작업이 가능하다.
- Nexo/Mattermost 등 외부 adapter는 예외로 두며, 이 작업은 ALT runtime API wrapper에만 손댄다.
- generated Dart contracts가 이미 있는 경우 wrapper만 추가하고, 없는 경우 contracts plan 결과에 맞춰 생성물을 갱신한다.

### 빌드 등급
- Build lane: `cloud-G07`
- Review lane: `cloud-G07`
- 근거: client runtime API surface와 generated protobuf 타입을 다루며, remote/web smoke 검증이 필요하다.

## 구현 체크리스트
### [CLIENT-1] backtest command wrapper 추가
문제:
client가 backtest 조회는 일부 호출할 수 있지만 start command wrapper가 없다.

해결 방법:
`AltSocketClient`에 `startBacktest`를 추가하고 generated `StartBacktestRequest/Response`를 그대로 사용한다. request ID/timeout 패턴은 기존 메서드와 동일하게 맞춘다.

수정 파일 및 체크리스트:
- `apps/client/lib/src/integrations/socket/alt_socket_client.dart`
- `apps/client/test/integrations/socket/alt_socket_client_test.dart`
- [ ] method name과 request/response type이 proto와 일치한다.
- [ ] 기존 wrapper style과 timeout/error handling을 유지한다.
- [ ] API 외 endpoint는 추가하지 않는다.

테스트 작성:
- fake communicator/mock transport로 message ID와 response type 검증.
- error path가 기존 wrapper와 같은 방식으로 전파되는지 확인.

중간 검증:
- 원격 검증 환경에서만 `cd apps/client && flutter test` 실행.

### [CLIENT-2] market query wrapper 추가
문제:
contracts에는 instruments/bars 요청이 있지만 client wrapper에 없다.

해결 방법:
`listInstruments`, `listBars` wrapper를 추가한다. status가 별도 contract로 존재하지 않으면 connection controller 상태 또는 common health contract를 우선 검토하고, 새 schema는 additive로만 추가한다.

수정 파일 및 체크리스트:
- `apps/client/lib/src/integrations/socket/alt_socket_client.dart`
- `apps/client/test/integrations/socket/alt_socket_client_test.dart`
- 필요 시 `apps/client/test/contracts/alt_contracts_test.dart`
- [ ] instruments/bars request가 API socket으로만 나간다.
- [ ] status 의미가 connection status인지 market data status인지 테스트명에서 구분된다.
- [ ] 외부 HTTP/gRPC runtime dependency를 추가하지 않는다.

테스트 작성:
- instruments request wrapper test.
- bars request wrapper test.
- status contract가 추가될 경우 contract export test.

중간 검증:
- 원격 검증 환경에서만 `cd apps/client && flutter test` 실행.

### [CLIENT-3] socket endpoint/control naming 정리
문제:
client 쪽에서 API 서버가 유일한 ALT-owned runtime endpoint라는 결정이 코드 naming에 덜 드러날 수 있다.

해결 방법:
기존 `socket_endpoint`와 `socket_connection_controller` 구조를 유지하되, 새 endpoint를 만들지 않는다. 필요한 경우 test description과 변수명에서 API socket임을 명확히 한다.

수정 파일 및 체크리스트:
- `apps/client/lib/src/integrations/socket/socket_endpoint.dart`
- `apps/client/lib/src/integrations/socket/socket_connection_controller.dart`
- 관련 tests
- [ ] direct worker endpoint 없음.
- [ ] dashboard/UI 변경은 이 계획 범위 밖이다.

테스트 작성:
- endpoint parsing/default test가 있으면 API URL 기준으로 보강.

중간 검증:
- 원격 검증 환경에서만 client smoke 명령을 실행한다.

## 수정 파일 요약
- 예상 코드: `apps/client/lib/src/integrations/socket/alt_socket_client.dart`
- 예상 테스트: `apps/client/test/integrations/socket/alt_socket_client_test.dart`, 필요 시 contracts test
- 조건부 코드: generated Dart contracts export

## 최종 검증
- 원격 검증 환경에서만 `cd apps/client && flutter test`
- 원격 검증 환경에서만 client socket runtime smoke
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
