# 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` |