alt/agent-roadmap/archive/phase/operator-surface/milestones/api-centered-proto-socket-rail.md

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 규칙으로 붙을 수 있는 내부 통신 기반을 만든다.

• [topology] client -> api -> worker를 기본 topology로 고정하고 client가 worker를 직접 제어하지 않도록 경계를 문서와 코드 구조에 반영한다.
• [api-hub] services/api가 operator-facing command/query facade와 proto-socket handler registry를 가진다. 검증: API socket handler 테스트가 hello 외 주요 command/query handler 등록과 request-response 경로를 검증한다.
• [client-api] Flutter client의 ALT 내부 통신은 AltSocketClient와 generated/mapped contracts를 통해 API에만 연결된다. 검증: Flutter socket integration 테스트가 연결, hello, 주요 request wrapper를 검증한다.
• [api-worker] API와 worker 사이의 내부 command/query/event 통신을 proto-socket으로 연결한다. 검증: Go integration 또는 smoke 테스트가 API에서 worker rail로 hello와 대표 command/query를 왕복한다.
• [contracts] client-api와 api-worker가 공유할 ALT protobuf message, parser map, codegen 경로를 정리한다. 검증: bin/contracts-check와 parser map 테스트가 통과한다.
• [backtest-rail] backtest run list/detail/result/compare/start 요청이 API를 통해 worker/store 실행 경계로 이어진다. 검증: client가 worker endpoint를 직접 호출하지 않고 API proto-socket 요청만으로 대표 backtest flow를 확인한다.
• [market-rail] market instrument/bar/status 조회 요청이 API proto-socket handler에서 worker-side read boundary로 이어진다. 검증: API proto-socket 요청으로 market data 대표 조회가 가능하다.
• [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 내 검증 근거가 충족된 완료 후보 상태다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • 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
• 확인 필요: 없음