toki/alt

toki c4a457c5c4 docs(agent-ops): domain rule과 로드맵을 operator reliability refactor에 맞게 갱신한다

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 전에
선행할 작업으로 변경한다.

2026-05-31 06:53:24 +09:00

4.3 KiB

Raw Blame History

domain	last_rule_review_commit	last_rule_updated_at
worker	`3b1be95e62`	2026-05-31

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을 통해 제어된다.

포함 경로

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/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/marketdata/ - market data import and data-check pipeline
services/worker/internal/providers/ - external market data provider adapters
services/worker/internal/rediskeys/ - worker Redis key naming helpers
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
services/worker/testdata/ - secret-free provider fixtures
services/worker/tools.go - tool dependency anchors
services/worker/go.mod - worker module metadata

제외 경로

services/api/ - client-facing socket sessions
packages/domain/ - shared domain types
deployments/local/ - local infra orchestration

주요 구성 요소

config.Config - database and Redis URLs
config.Load - environment variable parsing with local development defaults
cmd/alt-worker/main.go - worker process bootstrap and dependency wiring
socket.NewServer - worker proto-socket server construction
socket.Deps - socket handler dependency bundle for starter, analysis, result, instrument, and bar stores
jobs.Runner - registered job handler dispatcher
jobs.BacktestStarter - pending run persistence and asynchronous backtest job launch
backtest.Engine - strategy loop and result persistence
storage.Store - PostgreSQL-backed market/backtest store
marketdata/importer.Importer - provider-to-store daily bar import flow
providers/kis - KIS fixture decode and normalization adapter

유지할 패턴

Keep external service configuration explicit through DATABASE_URL and REDIS_URL.
Put job orchestration and worker-specific adapters under services/worker/internal.
Use packages/domain for shared business shapes instead of redefining market/backtest concepts.
Expose worker-owned command/query/event runtime boundaries to services/api through proto-socket when crossing process boundaries.
Wire worker execution dependencies in worker entrypoints or worker-internal constructors; API and client must only observe typed availability/errors.
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.

다른 도메인과의 경계

domain-model: worker consumes domain-model types; it should not make domain-model depend on worker infrastructure.
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.

금지 사항

Do not make worker packages import API internals.
Do not hide required infrastructure in package-level globals.
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.

4.3 KiB Raw Blame History