62 lines
4.1 KiB
Markdown
62 lines
4.1 KiB
Markdown
---
|
|
domain: contracts
|
|
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
|
|
last_rule_updated_at: 2026-06-24
|
|
---
|
|
|
|
# contracts
|
|
|
|
## 목적 / 책임
|
|
|
|
ALT 애플리케이션 레벨 protobuf 계약을 정의한다. proto-socket은 전송 계층으로 두고, ALT 메시지는 `PacketBase.data`에 실릴 payload schema로 관리한다. Market read/import/aggregation/scheduler, backtest lifecycle/analysis, paper trading, and live trading payloads are versioned here.
|
|
|
|
## 포함 경로
|
|
|
|
- `packages/contracts/README.md` - contract direction and compatibility notes
|
|
- `packages/contracts/gen/go/` - generated Go protobuf module for ALT contracts
|
|
- `packages/contracts/proto/alt/v1/` - versioned protobuf schema source
|
|
|
|
## 제외 경로
|
|
|
|
- `packages/domain/` - internal Go domain types
|
|
- `services/api/` - runtime socket server implementation
|
|
- `apps/client/` - generated or consumed client-side integration
|
|
|
|
## 주요 구성 요소
|
|
|
|
- `common.proto` - shared enums, decimal, handshake, and error messages
|
|
- `market.proto` - instrument, price, quantity, bar, market query, daily import, monthly aggregation, and scheduler refresh status messages
|
|
- `backtest.proto` - backtest run spec, lifecycle, analysis result, list/detail/compare requests, and responses
|
|
- `paper_trading.proto` - paper trading account state and virtual order lifecycle request/response messages
|
|
- `live_trading.proto` - live broker capability, order lifecycle, risk/kill switch, account snapshot, and audit query request/response messages
|
|
- `BacktestTrade`, `BacktestPosition`, `BacktestSummaryMetrics`, `BacktestEquityPoint`, `BacktestResult` - backtest analysis result payloads
|
|
- `ListBacktestRunsRequest`, `GetBacktestRunDetailRequest`, `GetBacktestResultRequest`, `CompareBacktestRunsRequest` - backtest analysis query request surface
|
|
- `ImportDailyBarsRequest`, `AggregateMonthlyBarsRequest`, `SchedulerRefreshStatusRequest` - market data operations and scheduler query request surface
|
|
- `StartPaperTradingRequest`, `SubmitPaperOrderRequest`, `FillPaperOrderRequest` - paper trading command surface
|
|
- `SubmitLiveOrderRequest`, `SetLiveKillSwitchRequest`, `SyncLiveAccountRequest`, `ListLiveAuditEventsRequest` - live trading control and audit surface
|
|
- `gen/go/alt/v1/*.pb.go` - generated Go message types consumed by Go services
|
|
|
|
## 유지할 패턴
|
|
|
|
- Prefer additive protobuf changes and reserve removal/renaming for explicit compatibility work.
|
|
- Keep schema package under `alt.v1` until a deliberate version bump is planned.
|
|
- Keep `option go_package` aligned with the generated Go package path.
|
|
- Keep generated Go module path aligned with `git.toki-labs.com/toki/alt/packages/contracts/gen/go`.
|
|
- Use explicit version/handshake messages because proto-socket protocol `0.1` does not carry an ALT application version field.
|
|
- Keep request/response contracts additive and update API, worker, and client parser maps when a new ALT protobuf message becomes part of the runtime surface.
|
|
- Keep market/venue/currency/timeframe enums broad enough for KR and US surfaces, but add provider-specific details in adapter/domain layers rather than hard-coding one broker into core contract names unless the message is explicitly broker-neutral.
|
|
- Keep live trading contracts sanitized: expose operator account aliases and broker-neutral status fields, not raw account numbers, tokens, or provider response bodies.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **api**: contracts define payload shape and generated Go message types; API decides transport/session behavior and owns API-local parser registration.
|
|
- **domain-model**: contracts are wire format; domain-model is internal business vocabulary.
|
|
- **client**: client consumes generated or mapped contracts; schema source remains here.
|
|
- **worker**: worker maps domain/storage/provider objects into generated contract payloads at socket adapter boundaries.
|
|
|
|
## 금지 사항
|
|
|
|
- Do not hand-edit generated outputs.
|
|
- Do not encode runtime server behavior or database concerns in `.proto` comments or fields.
|
|
- Do not change field numbers for existing protobuf fields.
|
|
- Do not place provider credentials, raw account identifiers, or raw external API payloads in contract messages.
|