diff --git a/agent-ops/rules/project/domain/api/rules.md b/agent-ops/rules/project/domain/api/rules.md index 32c353b..c1f2dec 100644 --- a/agent-ops/rules/project/domain/api/rules.md +++ b/agent-ops/rules/project/domain/api/rules.md @@ -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. diff --git a/agent-ops/rules/project/domain/client/rules.md b/agent-ops/rules/project/domain/client/rules.md index f6bff82..a73ec9c 100644 --- a/agent-ops/rules/project/domain/client/rules.md +++ b/agent-ops/rules/project/domain/client/rules.md @@ -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. diff --git a/agent-ops/rules/project/domain/contracts/rules.md b/agent-ops/rules/project/domain/contracts/rules.md index 9f99a29..f22e9c6 100644 --- a/agent-ops/rules/project/domain/contracts/rules.md +++ b/agent-ops/rules/project/domain/contracts/rules.md @@ -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. diff --git a/agent-ops/rules/project/domain/domain-model/rules.md b/agent-ops/rules/project/domain/domain-model/rules.md index 3c1f927..6c8f971 100644 --- a/agent-ops/rules/project/domain/domain-model/rules.md +++ b/agent-ops/rules/project/domain/domain-model/rules.md @@ -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. diff --git a/agent-ops/rules/project/domain/operations/rules.md b/agent-ops/rules/project/domain/operations/rules.md index 3a88717..08a5849 100644 --- a/agent-ops/rules/project/domain/operations/rules.md +++ b/agent-ops/rules/project/domain/operations/rules.md @@ -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. diff --git a/agent-ops/rules/project/domain/worker/rules.md b/agent-ops/rules/project/domain/worker/rules.md index c703c5b..6ffde2f 100644 --- a/agent-ops/rules/project/domain/worker/rules.md +++ b/agent-ops/rules/project/domain/worker/rules.md @@ -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.