update: domain rules sync (api, client, contracts, domain-model, operations, worker)
This commit is contained in:
parent
704f1eb232
commit
7bc31cca3f
6 changed files with 96 additions and 27 deletions
|
|
@ -1,14 +1,14 @@
|
|||
---
|
||||
domain: api
|
||||
last_rule_review_commit: 1f1527d7c6b8f115ba12c951c9919d779f071b23
|
||||
last_rule_updated_at: 2026-06-01
|
||||
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
|
||||
last_rule_updated_at: 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을 이 경계에서 관리한다.
|
||||
클라이언트-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로 전달한다.
|
||||
|
||||
## 포함 경로
|
||||
|
||||
|
|
@ -18,6 +18,7 @@ last_rule_updated_at: 2026-06-01
|
|||
- `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
|
||||
|
||||
## 제외 경로
|
||||
|
||||
|
|
@ -32,9 +33,11 @@ last_rule_updated_at: 2026-06-01
|
|||
- `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` and `ListBars` validation plus worker forwarding
|
||||
- `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
|
||||
- `workerclient.WorkerClient` - API-side worker request/response proxy for market reads and backtest command/query contracts
|
||||
- `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
|
||||
|
||||
|
|
@ -44,21 +47,22 @@ last_rule_updated_at: 2026-06-01
|
|||
- 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 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 long backtest/import work inline or own worker storage dependencies.
|
||||
- **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, or provider adapters to API internals.
|
||||
- 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.
|
||||
|
|
|
|||
|
|
@ -1,18 +1,19 @@
|
|||
---
|
||||
domain: client
|
||||
last_rule_review_commit: 1f1527d7c6b8f115ba12c951c9919d779f071b23
|
||||
last_rule_updated_at: 2026-06-01
|
||||
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
|
||||
last_rule_updated_at: 2026-06-24
|
||||
---
|
||||
|
||||
# client
|
||||
|
||||
## 목적 / 책임
|
||||
|
||||
ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, application shell, routing, feature presentation, socket integration adapters, optional external push integrations, and client-side tests belong here.
|
||||
ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, application shell, routing, feature presentation/data adapters, socket integration adapters, optional external push integrations, generated contract consumers, and client-side tests belong here.
|
||||
|
||||
## 포함 경로
|
||||
|
||||
- `apps/client/lib/main.dart` - Flutter app bootstrap
|
||||
- `apps/client/README.md` - client-local setup and notes
|
||||
- `apps/client/lib/src/app/` - app shell, theme, router
|
||||
- `apps/client/lib/src/contracts/` - client-side contract parser helpers
|
||||
- `apps/client/lib/src/features/` - feature presentation code
|
||||
|
|
@ -26,6 +27,7 @@ ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, appli
|
|||
- `apps/client/test_runtime/` - runtime smoke test helpers
|
||||
- `apps/client/analysis_options.yaml` - Dart analyzer configuration
|
||||
- `apps/client/pubspec.yaml` - Flutter package dependencies
|
||||
- `apps/client/pubspec.lock` - resolved Flutter dependency lockfile
|
||||
|
||||
## 제외 경로
|
||||
|
||||
|
|
@ -41,9 +43,12 @@ ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, appli
|
|||
- `appRouterProvider` - `go_router` configuration
|
||||
- `DashboardScreen` - initial responsive dashboard surface
|
||||
- `altParserMap` - generated ALT protobuf message parser registration for Dart clients
|
||||
- `AltApiResult`, `AltApiError`, and `AltTransportKind` - UI-copy-free API/transport result envelope for client repositories
|
||||
- `AltSocketClient` - proto-socket client wrapper for ALT request/response flows
|
||||
- `AltSocketEndpoint` - local/default socket endpoint value object
|
||||
- `SocketConnectionController` - Riverpod connection state controller for socket lifecycle
|
||||
- `MarketRepository` - socket-backed market list/bars data adapter returning `AltApiResult`
|
||||
- `BacktestRepository` - socket-backed backtest command/query data adapter returning `AltApiResult`
|
||||
- `MattermostPushHostIntegration` - optional external push integration boundary
|
||||
- `MattermostPushClient` and `MattermostPushPluginClient` - host-facing push abstraction and production plugin adapter
|
||||
- `MattermostAuthService` - optional Mattermost auth and FCM token registration service
|
||||
|
|
@ -53,10 +58,13 @@ ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, appli
|
|||
|
||||
- Keep app-level shell and router under `lib/src/app`.
|
||||
- Put user-facing screens under the `lib/src/features/feature-name/presentation` pattern.
|
||||
- Put feature data adapters under `lib/src/features/feature-name/data` when they wrap ALT socket calls for a feature.
|
||||
- Put socket and other external adapters under `lib/src/integrations`.
|
||||
- Keep the workbench shell as product skeleton and composition boundary. Real quant operation surfaces are mounted after API/worker/domain headless paths are stable.
|
||||
- Use sibling `agent_shell` for the common chat/agent UI only; keep ALT-specific market/backtest/portfolio logic in ALT client features or backend domains.
|
||||
- Treat files under `lib/src/generated` as generated outputs; update them through codegen.
|
||||
- Keep generated Dart parser registration aligned with every ALT protobuf message the client can decode, including paper/live trading messages when those surfaces are consumed.
|
||||
- Repositories should map typed `ErrorInfo` to `AltApiError` and transport/connect/decode failures to `AltTransportKind` without embedding presentation copy.
|
||||
- Use Material 3 components and responsive navigation patterns.
|
||||
- Test user-visible app shell behavior through Flutter tests.
|
||||
- Use `services/api` as the only ALT-owned runtime endpoint. Do not connect directly to worker runtime surfaces from client code.
|
||||
|
|
@ -64,6 +72,7 @@ ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, appli
|
|||
- Keep endpoint defaults in `AltSocketEndpoint` or provider/config boundaries; presentation widgets should consume state, not hard-code runtime endpoints.
|
||||
- Keep Mattermost/Firebase/platform-channel behavior under `lib/src/integrations` and out of dashboard presentation widgets.
|
||||
- Keep production access to `NexoMessagingPlugin.instance` behind `MattermostPushPluginClient`; tests and host orchestration should depend on `MattermostPushClient`.
|
||||
- Keep connection lifecycle state in `SocketConnectionController`; feature widgets and repositories should consume the injected/live socket client rather than owning global sockets.
|
||||
|
||||
## 다른 도메인과의 경계
|
||||
|
||||
|
|
@ -79,6 +88,7 @@ ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, appli
|
|||
- Do not hand-edit Flutter generated platform files or registrants unless a platform integration explicitly requires it.
|
||||
- Do not hand-edit generated protobuf Dart outputs.
|
||||
- Do not hard-code production endpoint assumptions in presentation widgets.
|
||||
- Do not put user-visible copy or layout decisions inside repository/result-envelope classes.
|
||||
- Do not put ALT-specific quant domain logic into `agent_shell`.
|
||||
- Do not add direct worker, database, Redis, or ALT-owned non-API runtime connections to Flutter client code.
|
||||
- Do not make push notification or Mattermost availability a prerequisite for the base operator shell unless a dedicated push Milestone explicitly changes that boundary.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
---
|
||||
domain: contracts
|
||||
last_rule_review_commit: 1f1527d7c6b8f115ba12c951c9919d779f071b23
|
||||
last_rule_updated_at: 2026-06-01
|
||||
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
|
||||
last_rule_updated_at: 2026-06-24
|
||||
---
|
||||
|
||||
# contracts
|
||||
|
||||
## 목적 / 책임
|
||||
|
||||
ALT 애플리케이션 레벨 protobuf 계약을 정의한다. proto-socket은 전송 계층으로 두고, ALT 메시지는 `PacketBase.data`에 실릴 payload schema로 관리한다. market read, backtest lifecycle, and backtest analysis query payloads are versioned here.
|
||||
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.
|
||||
|
||||
## 포함 경로
|
||||
|
||||
|
|
@ -25,10 +25,15 @@ ALT 애플리케이션 레벨 protobuf 계약을 정의한다. proto-socket은
|
|||
## 주요 구성 요소
|
||||
|
||||
- `common.proto` - shared enums, decimal, handshake, and error messages
|
||||
- `market.proto` - instrument, price, quantity, bar, and market query 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
|
||||
|
||||
## 유지할 패턴
|
||||
|
|
@ -39,15 +44,19 @@ ALT 애플리케이션 레벨 protobuf 계약을 정의한다. proto-socket은
|
|||
- 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.
|
||||
|
|
|
|||
|
|
@ -1,20 +1,21 @@
|
|||
---
|
||||
domain: domain-model
|
||||
last_rule_review_commit: 1f1527d7c6b8f115ba12c951c9919d779f071b23
|
||||
last_rule_updated_at: 2026-06-01
|
||||
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
|
||||
last_rule_updated_at: 2026-06-24
|
||||
---
|
||||
|
||||
# domain-model
|
||||
|
||||
## 목적 / 책임
|
||||
|
||||
ALT의 핵심 business vocabulary를 Go 타입으로 표현한다. market, instrument, price, bar, backtest run, strategy, portfolio state, and analysis result concepts stay transport- and storage-free here.
|
||||
ALT의 핵심 business vocabulary를 Go 타입으로 표현한다. Market, instrument, price, bar, backtest run, strategy, portfolio state, paper account, live trading account/order/risk/audit, and analysis result concepts stay transport- and storage-free here.
|
||||
|
||||
## 포함 경로
|
||||
|
||||
- `packages/domain/` - shared Go domain model module
|
||||
- `packages/domain/market/` - market, venue, currency, instrument, OHLCV bar types
|
||||
- `packages/domain/backtest/` - backtest run spec, run state, result types
|
||||
- `packages/domain/trading/` - broker-neutral live trading account, order, risk, capability, and audit types
|
||||
|
||||
## 제외 경로
|
||||
|
||||
|
|
@ -25,14 +26,21 @@ ALT의 핵심 business vocabulary를 Go 타입으로 표현한다. market, instr
|
|||
## 주요 구성 요소
|
||||
|
||||
- `market.Instrument` - tradable instrument identity and provider symbol mapping
|
||||
- `market.AssetType` and `market.VenueMetadata` - venue/market/currency metadata for KR and US market data
|
||||
- `market.UniverseSelector` - provider import universe vocabulary
|
||||
- `market.ProviderCapability` and `market.ProviderCapabilityRule` - provider/venue/asset type/timeframe capability matrix
|
||||
- `market.Bar` - timeframe OHLCV market data point
|
||||
- `backtest.RunSpec` - strategy, market, timeframe, period inputs for a run
|
||||
- `backtest.InputSelector` - optional instrument/symbol selector for backtest bar source filtering
|
||||
- `backtest.Run` - backtest lifecycle state
|
||||
- `backtest.Result` - backtest financial summary, trades, positions, summary metrics, and equity curve
|
||||
- `backtest.Strategy`, `backtest.StrategyInput`, `backtest.OrderIntent` - strategy execution vocabulary
|
||||
- `backtest.PortfolioState`, `backtest.Fill`, `backtest.Position` - portfolio accounting state and fill application
|
||||
- `backtest.PaperAccount`, `backtest.RiskSettings`, `backtest.CheckRisk`, and `backtest.FillOrderOnDailyBar` - paper trading simulation vocabulary and daily OHLC fill semantics
|
||||
- `backtest.TotalReturn` - decimal return calculation helper backed by rational arithmetic
|
||||
- `trading.OrderIntent`, `trading.AccountSnapshot`, `trading.PositionSnapshot`, and `trading.BrokerCapability` - broker-neutral live trading vocabulary
|
||||
- `trading.RiskPolicy`, `trading.KillSwitchState`, `trading.EvaluateRisk` - live risk and kill switch decision vocabulary
|
||||
- `trading.AuditEvent`, `trading.AuditFilter`, `trading.HasRawSecretKey` - sanitized live operation audit vocabulary
|
||||
|
||||
## 유지할 패턴
|
||||
|
||||
|
|
@ -40,11 +48,14 @@ ALT의 핵심 business vocabulary를 Go 타입으로 표현한다. market, instr
|
|||
- Decimal values are represented as strings through `market.Decimal`; avoid float types for prices and quantities.
|
||||
- Portfolio and return calculations use exact decimal/rational conversion, not floating point arithmetic.
|
||||
- Keep package dependencies inward: domain packages should not import API, worker, CLI, Flutter, protobuf generated code, database drivers, or proto-socket.
|
||||
- Keep provider and broker vocabularies open string types where external systems may introduce new values.
|
||||
- Treat account IDs in `trading` as operator aliases or internal identifiers; raw broker account numbers, tokens, and provider bodies must be stripped before domain objects are created.
|
||||
- Keep provider capability decisions in domain-model, while provider-specific fetch/auth behavior remains in worker adapters.
|
||||
|
||||
## 다른 도메인과의 경계
|
||||
|
||||
- **contracts**: domain-model owns internal Go vocabulary; contracts owns protobuf wire schema and compatibility.
|
||||
- **worker**: domain-model defines the shapes; worker executes imports, normalization, backtests, persistence, and socket mapping.
|
||||
- **worker**: domain-model defines the shapes; worker executes imports, normalization, backtests, paper/live trading, persistence, provider calls, scheduler work, and socket mapping.
|
||||
- **api**: domain-model may be mapped to responses, but API transport details stay outside this module.
|
||||
|
||||
## 금지 사항
|
||||
|
|
@ -52,3 +63,4 @@ ALT의 핵심 business vocabulary를 Go 타입으로 표현한다. market, instr
|
|||
- Do not add persistence annotations, socket parser logic, or environment configuration here.
|
||||
- Do not introduce generated protobuf code into this package.
|
||||
- Do not use `float32` or `float64` for money, price, or quantity values.
|
||||
- Do not store raw account numbers, access tokens, app secrets, authorization headers, or raw external provider payloads in domain objects or audit payloads.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
---
|
||||
domain: operations
|
||||
last_rule_review_commit: 1f1527d7c6b8f115ba12c951c9919d779f071b23
|
||||
last_rule_updated_at: 2026-06-01
|
||||
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
|
||||
last_rule_updated_at: 2026-06-24
|
||||
---
|
||||
|
||||
# operations
|
||||
|
||||
## 목적 / 책임
|
||||
|
||||
로컬 개발, remote verification routing, workspace orchestration, operator CLI, generated output checks, and infrastructure entrypoints를 관리한다. 개발자와 agent가 반복적으로 쓰는 root-level commands, local/remote test rules, and service entrypoints stay discoverable here.
|
||||
로컬 개발, remote verification routing, workspace orchestration, operator CLI/headless scenario fixtures, generated output checks, KIS smoke wrappers, and infrastructure entrypoints를 관리한다. 개발자와 agent가 반복적으로 쓰는 root-level commands, local/remote test rules, and service entrypoints stay discoverable here.
|
||||
|
||||
## 포함 경로
|
||||
|
||||
|
|
@ -26,6 +26,7 @@ last_rule_updated_at: 2026-06-01
|
|||
- `services/worker/` - worker runtime implementation
|
||||
- `apps/client/` - Flutter client code
|
||||
- `packages/domain/` and `packages/contracts/` - shared model and schema sources
|
||||
- `secrets/` - local/private secret material used by wrappers, not tracked operational guidance
|
||||
|
||||
## 주요 구성 요소
|
||||
|
||||
|
|
@ -38,8 +39,16 @@ last_rule_updated_at: 2026-06-01
|
|||
- `bin/infra-check` - checks PostgreSQL/Redis availability for the configured environment
|
||||
- `bin/worker-storage-gen` - regenerates worker sqlc outputs
|
||||
- `bin/worker-storage-check` - checks worker sqlc generated output drift
|
||||
- `bin/kis-paper-daily-smoke` - secret-redacting KIS daily price smoke wrapper for paper/real env credentials
|
||||
- `bin/kis-sops-env` - decrypts local SOPS KIS env and execs a command without writing tracked secrets
|
||||
- `deployments/local/docker-compose.yml` - PostgreSQL and Redis local stack
|
||||
- `apps/cli/cmd/alt/main.go` - operator CLI scaffold
|
||||
- `apps/cli/internal/cli` - CLI command dispatch and exit-code contract
|
||||
- `apps/cli/internal/operator.APIClient` - proto-socket client for headless operator scenarios
|
||||
- `apps/cli/internal/operator.Scenario` - strict YAML schema and dry-run validation for operator workflows
|
||||
- `apps/cli/internal/operator.RunScenario` - scenario runner for market, backtest, paper, live, and scheduler actions
|
||||
- `apps/cli/internal/operator.Writer` - machine-readable text/jsonl step and summary output
|
||||
- `apps/cli/testdata/operator/` - headless scenario fixtures and expected JSONL outputs
|
||||
- `agent-test/local/rules.md` - local profile routing with remote host execution policy
|
||||
|
||||
## 유지할 패턴
|
||||
|
|
@ -52,6 +61,9 @@ last_rule_updated_at: 2026-06-01
|
|||
- Add new Go modules to `go.work` when they are part of local development.
|
||||
- Treat `agent-test/local` as a local profile whose commands run from the remote ALT checkout; do not imply local shell execution when local testing is forbidden.
|
||||
- Keep root scripts explicit: generated drift checks should fail loudly and tell the user which generation command to run.
|
||||
- Keep operator CLI stdout machine-readable; send usage and human-readable error detail to stderr.
|
||||
- Keep operator scenario validation strict: unsupported actions, enum strings, malformed duration/date fields, and expectation typos should fail before runtime execution.
|
||||
- Keep KIS wrappers redacting tokens, app secrets, account numbers, and provider response snippets before printing diagnostics.
|
||||
|
||||
## 다른 도메인과의 경계
|
||||
|
||||
|
|
@ -59,6 +71,7 @@ last_rule_updated_at: 2026-06-01
|
|||
- **client**: operations invokes Flutter commands; UI implementation stays under `apps/client`.
|
||||
- **contracts**: operations may run codegen later; schema design remains in contracts.
|
||||
- **agent-test**: operations owns routing to test profiles, but domain-specific smoke criteria remain in each `agent-test/local/*-smoke.md` document.
|
||||
- **private rules/secrets**: operations can reference secret-loading wrappers, but secret values and machine-specific endpoints remain untracked/private.
|
||||
|
||||
## 금지 사항
|
||||
|
||||
|
|
@ -66,3 +79,4 @@ last_rule_updated_at: 2026-06-01
|
|||
- Do not commit local secrets or machine-specific state.
|
||||
- Do not make root scripts silently skip failing module checks.
|
||||
- Do not record raw remote paths, tokens, passwords, account numbers, or personal endpoints in tracked test rules or command output.
|
||||
- Do not make operator scenario fixtures depend on live credentials unless the command explicitly routes through a private/env wrapper.
|
||||
|
|
|
|||
|
|
@ -1,28 +1,33 @@
|
|||
---
|
||||
domain: worker
|
||||
last_rule_review_commit: 1f1527d7c6b8f115ba12c951c9919d779f071b23
|
||||
last_rule_updated_at: 2026-06-01
|
||||
last_rule_review_commit: 704f1eb23260d5a82b0b134eab6c6470b1b4256a
|
||||
last_rule_updated_at: 2026-06-24
|
||||
---
|
||||
|
||||
# worker
|
||||
|
||||
## 목적 / 책임
|
||||
|
||||
데이터 수집, 정규화, backtest 실행, scheduled jobs처럼 오래 걸리거나 비동기적인 작업의 runtime surface를 담당한다. PostgreSQL/Redis integration, worker socket command/query handlers, provider adapters, storage ports, and execution wiring은 이 경계에서 운영 관점으로 다룬다. worker는 client-facing surface가 아니며 API control plane을 통해 제어된다.
|
||||
데이터 수집, 정규화, backtest 실행, scheduled jobs, paper trading, live trading처럼 오래 걸리거나 비동기적이거나 provider/storage 의존성이 있는 작업의 runtime surface를 담당한다. PostgreSQL/Redis integration, worker socket command/query handlers, provider adapters, scheduler state, storage ports, broker boundaries, and execution wiring은 이 경계에서 운영 관점으로 다룬다. worker는 client-facing surface가 아니며 API control plane을 통해 제어된다.
|
||||
|
||||
## 포함 경로
|
||||
|
||||
- `services/worker/cmd/alt-worker/` - worker process entrypoint
|
||||
- `services/worker/cmd/alt-worker-data-check/` - credential-free data pipeline smoke command
|
||||
- `services/worker/cmd/alt-worker-migrate/` - PostgreSQL migration command
|
||||
- `services/worker/cmd/alt-worker-schedule-check/` - scheduler validation/status smoke command
|
||||
- `services/worker/README.md` - worker service notes
|
||||
- `services/worker/internal/backtest/` - backtest execution engine
|
||||
- `services/worker/internal/config/` - worker runtime configuration
|
||||
- `services/worker/internal/contracts/` - worker-local ALT protobuf parser map
|
||||
- `services/worker/internal/jobs/` - worker job runner, payloads, and execution starters
|
||||
- `services/worker/internal/livetrading/` - live trading broker boundary, risk/kill switch, account snapshot, and audit orchestration
|
||||
- `services/worker/internal/marketdata/` - market data import and data-check pipeline
|
||||
- `services/worker/internal/marketdata/aggregation/` - deterministic daily-to-monthly bar aggregation with provenance
|
||||
- `services/worker/internal/papertrading/` - process-local paper trading engine, state, and virtual order lifecycle
|
||||
- `services/worker/internal/providers/` - external market data provider adapters
|
||||
- `services/worker/internal/rediskeys/` - worker Redis key naming helpers
|
||||
- `services/worker/internal/scheduler/` - market refresh schedule validation, ticks, backfill decisions, and runtime refresh status
|
||||
- `services/worker/internal/socket/` - worker proto-socket command/query surface
|
||||
- `services/worker/internal/storage/` - storage ports and PostgreSQL implementation
|
||||
- `services/worker/sqlc.yaml` - worker SQL codegen configuration
|
||||
|
|
@ -47,11 +52,18 @@ last_rule_updated_at: 2026-06-01
|
|||
- `jobs.BacktestStarter` - pending run persistence and asynchronous backtest job launch
|
||||
- `jobs.RegisterRunBacktestHandler` - run status transition and execution job handler
|
||||
- `jobs.RegisterDailyBarImportHandler` - provider-specific daily bar import job handler
|
||||
- `backtest.StorageBarSource` - store-backed bar source for backtest and paper execution
|
||||
- `backtest.BuiltInStrategyPort` - worker-local built-in strategy resolver
|
||||
- `backtest.Engine` - strategy loop and result persistence
|
||||
- `storage.BacktestAnalysisStore` - list/detail/compare read surface for backtest analysis
|
||||
- `storage.Store` - PostgreSQL-backed market/backtest store implementing run, result, analysis, instrument, and bar ports
|
||||
- `storage.LiveAuditStore` - durable live operation audit event port
|
||||
- `storage.Store` - PostgreSQL-backed market/backtest/live-audit store implementing run, result, analysis, instrument, bar, and audit ports
|
||||
- `marketdata/importer.Importer` - provider-to-store daily bar import flow
|
||||
- `providers/kis` - KIS fixture decode and normalization adapter
|
||||
- `marketdata/aggregation.Aggregator` and `AggregateDailyToMonthly` - daily-to-monthly OHLCV aggregation and provenance
|
||||
- `scheduler.RunTick`, `DecideBackfill`, and `RefreshStatusStore` - scheduled import execution, backfill/readiness decisions, and runtime status memory
|
||||
- `papertrading.Engine` and `papertrading.Service` - daily paper execution, state inspection, and virtual order lifecycle
|
||||
- `livetrading.Service` and `livetrading.BrokerPort` - live broker capability/order/account boundary with operator confirmation, risk policy, kill switch, and audit
|
||||
- `providers/kis` - KIS daily bar fixture/live decode, normalization, auth, and paper/real environment adapter
|
||||
|
||||
## 유지할 패턴
|
||||
|
||||
|
|
@ -63,6 +75,11 @@ last_rule_updated_at: 2026-06-01
|
|||
- Keep store-backed socket surfaces tolerant of unavailable dependencies by returning typed contract errors instead of panicking.
|
||||
- Keep provider fixtures secret-free and provider-specific raw payload handling inside provider/marketdata adapters.
|
||||
- Keep backtest start asynchronous: socket handlers record or read state synchronously, while execution runs through worker job handlers.
|
||||
- Keep worker socket `Deps` as the capability gate: nil dependencies disable only their related handler/capability surface.
|
||||
- Keep daily import and monthly aggregation worker-owned; API/CLI may request them but must not execute provider fetches or storage writes.
|
||||
- Keep scheduler status evidence derived from actual import results; do not fabricate success, counts, or `last_success` from no-item or no-evidence ticks.
|
||||
- Keep live order submission behind operator confirmation, kill switch, and risk policy evaluation before any broker call.
|
||||
- Keep live audit payloads sanitized; reject raw secret/account/provider-body keys before persistence.
|
||||
|
||||
## 다른 도메인과의 경계
|
||||
|
||||
|
|
@ -70,6 +87,7 @@ last_rule_updated_at: 2026-06-01
|
|||
- **api**: API may request or observe work; worker owns execution.
|
||||
- **operations**: Docker Compose supplies local infrastructure; worker code owns runtime behavior.
|
||||
- **contracts**: worker consumes generated ALT protobuf types in socket/contracts adapters; protobuf source remains in `packages/contracts`.
|
||||
- **private rules/secrets**: worker reads runtime credentials from environment/private wrappers; tracked worker docs, fixtures, logs, and tests must stay secret-free.
|
||||
|
||||
## 금지 사항
|
||||
|
||||
|
|
@ -78,3 +96,5 @@ last_rule_updated_at: 2026-06-01
|
|||
- Do not store generated contract code in the worker module.
|
||||
- Do not expose worker as a direct Flutter/client runtime endpoint.
|
||||
- Do not put provider credentials, account numbers, raw tokens, or personal endpoints in worker fixtures, logs, README, or tracked docs.
|
||||
- Do not let live broker adapters return raw account numbers, authorization headers, tokens, or raw provider payloads across the `BrokerPort` boundary.
|
||||
- Do not mark scheduler refresh status successful without actual item evidence when evidence is required by the status store contract.
|
||||
|
|
|
|||
Loading…
Reference in a new issue