alt/agent-ops/rules/project/domain/worker/rules.md

domain	last_rule_review_commit	last_rule_updated_at
worker	1f1527d7c6	2026-06-01

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/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/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
• jobs.RegisterRunBacktestHandler - run status transition and execution job handler
• jobs.RegisterDailyBarImportHandler - provider-specific daily bar import job handler
• 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
• 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.
• Keep backtest start asynchronous: socket handlers record or read state synchronously, while execution runs through worker job handlers.

다른 도메인과의 경계

• 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.