toki
87c7f9cdee
API/worker runtime default와 local infra host publish가 같은 포트 정책을 사용하도록 맞춘다.\n\nagent-task 리뷰 산출물을 함께 남겨 포트 표준화 작업의 검토 이력을 추적할 수 있게 한다.
53 lines
3.3 KiB
Markdown
53 lines
3.3 KiB
Markdown
# ALT Worker Service
|
|
|
|
The Worker service handles background tasks, such as market data imports, data normalization, and backtest execution.
|
|
|
|
## Market Data Provider Boundary
|
|
|
|
ALT starts with KIS/Korea daily bars as the first provider and venue validation path, but the worker boundary should keep the canonical model equity venue-agnostic. KRX-specific or KIS-specific fields belong in provider adapters, venue metadata, raw payload storage, or explicit extension metadata instead of becoming required core columns.
|
|
|
|
Crypto is out of scope for the current stock-oriented market model. If a later crypto data domain is added, it may reuse generic import-run, provider mapping, raw-payload, and OHLCV pipeline concepts, but pair/funding/24-7 market semantics should not be forced into the equity model.
|
|
|
|
## Provider Reference and Mock Fixtures
|
|
|
|
KIS adapter mapping should start from the locally cached official sample repository, not from a required Postman export. The cache path is documented in the private rules because it is local machine state, not an ALT source dependency.
|
|
|
|
- Store mock-provider request/response fixtures under `services/worker/testdata/providers/kis/`.
|
|
- Remove app keys, tokens, account numbers, personal identifiers, and live secret references before committing any fixture.
|
|
- Prefer JSON for initial adapter mapping because it is readable, diffable, and close to the KIS REST payload shape.
|
|
- Consider SQLite only after the fixture corpus is large enough to need indexed lookup or query-based comparison.
|
|
|
|
Provider credentials are not required for mock tests. When live KIS smoke tests are added later, KIS agent runtime secrets should come from SOPS + age and be injected only for the command lifetime.
|
|
|
|
## Redis Usage Guidelines
|
|
|
|
### Purpose
|
|
Redis is used as a lightweight, high-performance messaging, coordination, and caching layer for background jobs. It is **not** a source of truth. All critical system states and historical datasets reside in PostgreSQL.
|
|
|
|
### Key Prefixing Standard
|
|
To avoid key collisions and maintain organization, all keys created by the worker **must** use the designated helper package `internal/rediskeys` and strictly follow the format:
|
|
|
|
```
|
|
<prefix>:worker:<purpose>:<id>
|
|
```
|
|
|
|
- `<prefix>`: Configured via `ALT_REDIS_KEY_PREFIX` (defaults to `alt`). This segregates environments or local dev workspaces.
|
|
- `worker`: Hardcoded namespace denoting worker-owned keys.
|
|
- `<purpose>`: Lowercase segment describing the domain or usage (e.g. `job`, `lock`, `cache`).
|
|
- `<id>`: Unique identifier for the specific object (e.g., job ID, lock name).
|
|
|
|
Always utilize `rediskeys.WorkerKey(prefix, purpose, id)` instead of assembling key strings manually.
|
|
|
|
## Configuration
|
|
|
|
Environment variables can be used to customize worker runtime:
|
|
|
|
| Variable | Description | Default |
|
|
|---|---|---|
|
|
| `DATABASE_URL` | PostgreSQL connection string | `postgres://alt:alt@localhost:15430/alt?sslmode=disable` |
|
|
| `REDIS_URL` | Redis connection string | `redis://localhost:16330/0` |
|
|
| `ALT_WORKER_HOST` | Worker bind host | `127.0.0.1` |
|
|
| `ALT_WORKER_PORT` | Worker listen port | `18031` |
|
|
| `ALT_WORKER_SOCKET_PATH` | Worker WebSocket path | `/socket` |
|
|
| `ALT_REDIS_KEY_PREFIX` | Namespace prefix for Redis keys | `alt` |
|
|
| `ALT_WORKER_QUEUE` | Target worker queue to consume from | `default` |
|