alt/agent-ops/rules/project/domain/api/rules.md

domain	last_rule_review_commit	last_rule_updated_at
api	704f1eb232	2026-06-24

api

목적 / 책임

클라이언트-facing socket API endpoint와 ALT operator-facing control plane을 제공한다. proto-socket server lifecycle, connection setup, heartbeat timing, ALT protobuf parser registration, API configuration, and worker-facing client proxy lifecycle을 이 경계에서 관리한다. Market, backtest, paper trading, live trading, scheduler query 요청은 API에서 shape만 검증하고 worker-owned surface로 전달한다.

포함 경로

• services/api/cmd/alt-api/ - API service entrypoint
• services/api/internal/config/ - API environment configuration
• services/api/internal/contracts/ - API-local ALT protobuf parser map
• services/api/internal/socket/ - client-facing proto-socket server, session handlers, worker forwarding
• services/api/internal/workerclient/ - API-owned proto-socket client proxy to worker
• services/api/go.mod - API module dependencies
• services/api/go.sum - API module dependency checksums

제외 경로

• services/worker/ - long-running jobs and backtest execution
• packages/contracts/ - protobuf schema source
• packages/domain/ - transport-free domain vocabulary
• apps/client/ - UI and client navigation

주요 구성 요소

• config.Config - host, port, socket path, heartbeat timing, WebSocket origin patterns, and worker socket URL
• config.Load - environment variable parsing with local fallback defaults
• contracts.ParserMap - parser registration for generated ALT protobuf messages
• socket.NewServer - proto-socket WsServer construction and session handler registration
• socket.marketHandlers - ListInstruments, ListBars, ImportDailyBars, AggregateMonthlyBars, and SchedulerRefreshStatus validation plus worker forwarding
• socket.backtestHandlers - start, list, detail, result, and compare backtest request validation plus worker forwarding
• socket.paperHandlers - start/state/order lifecycle paper trading validation plus worker forwarding
• socket.apiLiveHandlers - live capability, order lifecycle, risk/kill switch, account sync, and audit query validation plus worker forwarding
• workerclient.WorkerClient - API-side worker request/response proxy for market, backtest, paper, live, and scheduler contracts
• workerclient.sendTyped - shared worker forwarding path for timeout, unavailable, and context cancellation mapping
• cmd/alt-api/main.go - signal handling and service lifecycle

유지할 패턴

• Read configuration from environment variables with explicit local defaults.
• Keep process lifecycle in cmd/alt-api; keep reusable socket construction under internal/socket.
• Keep ALT protobuf parser registration under internal/contracts and inject it into proto-socket server construction.
• Treat proto-socket as the transport abstraction; ALT payload parsing should be derived from contracts.
• Keep client-facing command/query handling in API thin: validate request shape, map transport failures to typed contract errors, and route long-running execution, broker calls, scheduler state, storage-backed reads, and worker-owned writes through the worker boundary.
• Keep worker connectivity lifecycle observable and injectable enough for tests; avoid spreading worker connection state through unrelated API packages.
• Keep HelloResponse.capabilities aligned with actually registered API session handlers.
• Bound forwarded worker calls with a context timeout and return typed ErrorInfo payloads instead of leaking Go handler errors to clients.
• Keep API-local parser registration complete for every ALT protobuf message that can cross the client/API or API/worker proto-socket boundary.

다른 도메인과의 경계

• contracts: API imports generated contract packages and owns API-local parser registration, but contract source stays in packages/contracts.
• worker: API may forward commands/queries to worker and surface worker availability, but should not run backtest/import/aggregation/scheduler/paper/live work inline or own worker storage/provider dependencies.
• client: API serves client sessions; client UI state and navigation stay in Flutter.

금지 사항

• Do not add direct Flutter/client assumptions to API internals.
• Do not put scheduled job loops or heavy data processing in the API service.
• Do not add worker execution engines, PostgreSQL stores, Redis queues, scheduler runners, broker clients, paper/live trading engines, or provider adapters to API internals.
• Do not bypass proto-socket for the main client session path without an explicit architecture update.
• Do not require Flutter client or any external operator surface to connect directly to worker runtime surfaces.