# Milestone: API-Centered Proto-Socket Rail

## 위치

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

## 목표

ALT 내부 runtime boundary의 application message 통신을 API 서버 중심의 proto-socket rail로 정리한다. client는 API만 바라보고, API는 worker와 proto-socket 기반 command/query/event 경계를 가져서 operator console과 후속 자동화가 같은 통신 경로를 쓰게 한다. 별도 core 서버는 두지 않고 `services/api`가 얇은 control plane 역할을 맡는다.

## 상태

[완료]

## 구현 잠금

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

## 범위

- client-api proto-socket 단일 진입점
- api-worker proto-socket 내부망
- API 서버의 control plane 역할과 worker 실행자 경계
- ALT protobuf contract와 parser map 정합성
- 내부 command/query/event handler 등록 패턴
- backtest run, result, market data 조회/실행 요청의 통신 레일
- local smoke/integration 검증 경로

## 기능

### Epic: [proto-rail] API-centered proto-socket rail

API 서버를 중심으로 client, worker, 후속 sidecar가 같은 proto-socket 규칙으로 붙을 수 있는 내부 통신 기반을 만든다.

- [x] [topology] `client -> api -> worker`를 기본 topology로 고정하고 client가 worker를 직접 제어하지 않도록 경계를 문서와 코드 구조에 반영한다.
- [x] [api-hub] `services/api`가 operator-facing command/query facade와 proto-socket handler registry를 가진다. 검증: API socket handler 테스트가 hello 외 주요 command/query handler 등록과 request-response 경로를 검증한다.
- [x] [client-api] Flutter client의 ALT 내부 통신은 `AltSocketClient`와 generated/mapped contracts를 통해 API에만 연결된다. 검증: Flutter socket integration 테스트가 연결, hello, 주요 request wrapper를 검증한다.
- [x] [api-worker] API와 worker 사이의 내부 command/query/event 통신을 proto-socket으로 연결한다. 검증: Go integration 또는 smoke 테스트가 API에서 worker rail로 hello와 대표 command/query를 왕복한다.
- [x] [contracts] client-api와 api-worker가 공유할 ALT protobuf message, parser map, codegen 경로를 정리한다. 검증: `bin/contracts-check`와 parser map 테스트가 통과한다.
- [x] [backtest-rail] backtest run list/detail/result/compare/start 요청이 API를 통해 worker/store 실행 경계로 이어진다. 검증: client가 worker endpoint를 직접 호출하지 않고 API proto-socket 요청만으로 대표 backtest flow를 확인한다.
- [x] [market-rail] market instrument/bar/status 조회 요청이 API proto-socket handler에서 worker-side read boundary로 이어진다. 검증: API proto-socket 요청으로 market data 대표 조회가 가능하다.
- [x] [exceptions] PostgreSQL, Redis, filesystem, 외부 provider, Nexo/Mattermost/Firebase/platform channel은 adapter 예외로 유지하고 ALT-owned runtime message protocol로 확장하지 않는다. 검증: 새 ALT-owned HTTP/gRPC/direct-worker path가 추가되지 않았음을 코드 검색 또는 리뷰로 확인한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-05-31
- 완료 근거: `agent-task/archive/2026/05/m-api-centered-proto-socket-rail/01_contracts_api_registry/complete.log`에서 API handler registry, parser map, `bin/contracts-check`, `go test ./services/api/...` PASS를 확인했다.
- 완료 근거: `02+01_worker_socket_rail`, `03+01_client_api_wrappers`, `04+02_backtest_rail`, `05+02_market_rail` 완료 로그에서 worker rail, Flutter API wrappers, backtest rail, market rail의 최종 PASS와 API/worker/client/contracts 검증 통과를 확인했다.
- 완료 근거: 기존 `topology`, `exceptions` 완료와 합쳐 모든 기능 Task와 Task 내 검증 근거가 충족된 완료 후보 상태다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-05-31 사용자 요청으로 완료 승인 후 archive 이동했다.

## 범위 제외

- 별도 core 서버 신설
- Flutter operator 화면 완성
- 고급 charting과 UI polish
- worker의 장기 실행 작업 자체 구현 확대
- PostgreSQL/Redis native protocol 대체
- 외부 provider, push notification, platform channel protocol 대체

## 작업 컨텍스트

- 관련 경로: `services/api/`, `services/worker/`, `apps/client/`, `packages/contracts/`
- 표준선(선택): ALT-owned runtime boundary의 application message 통신은 proto-socket과 ALT protobuf payload를 기본값으로 삼고, `services/api`를 얇은 control plane으로 둔다.
- 즉시 처리: `topology`, `exceptions`, `api-hub`, `client-api`, `api-worker`, `contracts`, `backtest-rail`, `market-rail`을 완료 로그와 검증 근거에 맞춰 반영했다.
- 대형 작업 plan: `agent-task/m-api-centered-proto-socket-rail/` 완료 로그는 `agent-task/archive/2026/05/m-api-centered-proto-socket-rail/`에 있다.
- 선행 작업: Nexo 최신화 및 테스트 완료, Socket Session Loop, Backtest Analysis Surface
- 후속 작업: Flutter Operator Console
- 확인 필요: 없음
