toki
c4a457c5c4
API domain에 workerclient proxy와 handler responsibility를 추가하고, worker domain에 backtest engine, storage, provider, socket surface를 명시한다. Client domain에 socket integration과 push integration 경계를 보강한다. Operations domain에 agent-test/local과 bin 명령어를 포함하며, operations domain table에 agent-test/local 경계를 추가한다. 로드맵에 Operator Runtime Reliability Refactor Milestone를 추가하고 현재 활성 Milestone으로 설정하여 Flutter Operator Console 전에 선행할 작업으로 변경한다.
61 lines
3.5 KiB
Markdown
61 lines
3.5 KiB
Markdown
---
|
|
domain: api
|
|
last_rule_review_commit: 3b1be95e625cfd110a42d2ee0d12653dc35f7579
|
|
last_rule_updated_at: 2026-05-31
|
|
---
|
|
|
|
# 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을 이 경계에서 관리한다.
|
|
|
|
## 포함 경로
|
|
|
|
- `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/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 interval, heartbeat wait
|
|
- `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`, `socket.backtestHandlers` - request validation and worker forwarding handlers
|
|
- `workerclient.WorkerClient` - API-side worker request/response proxy
|
|
- `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 or worker-owned reads 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.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **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 long backtest/import work inline or own worker storage 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, 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.
|