# 调度配置说明

## 1. 运行模式概览

系统支持两种运行模式：

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **任务模式** | 通过 `--tasks` 指定具体任务代码 | 单任务调试、手动补数 |
| **Flow 模式** | 通过 `--flow` 或 `--layers` 指定 Flow 类型或层组合 | 日常增量、全流程运行 |

## 2. CLI 参数详解

### 2.1 基本参数

```bash
python -m cli.main [参数]
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `--store-id` | 门店 ID（整数） | `--store-id 1` |
| `--tasks` | 任务列表，逗号分隔（任务模式） | `--tasks ODS_MEMBER,ODS_ORDER` |
| `--dry-run` | 试运行，不提交数据库事务 | `--dry-run` |
| `--pg-dsn` | PostgreSQL 连接字符串 | `--pg-dsn "postgresql://..."` |
| `--api-token` | API Bearer Token | `--api-token "xxx"` |

### 2.2 Flow 参数

| 参数 | 说明 | 可选值 |
|------|------|--------|
| `--flow` | Flow 类型 | 见下方 Flow 定义表 |
| `--pipeline` | [已弃用] `--flow` 的别名 | 同上，使用时输出 DeprecationWarning |
| `--layers` | ETL 层自由组合（与 `--flow`/`--pipeline` 互斥） | ODS,DWD,DWS,INDEX 的逗号分隔组合 |
| `--processing-mode` | 处理模式（默认 `increment_only`） | `increment_only` / `verify_only` / `increment_verify` |
| `--fetch-before-verify` | 校验前先从 API 获取数据 | 仅在 `verify_only` 模式下有效 |
| `--verify-tables` | 仅校验指定表（逗号分隔） | `--verify-tables "dim_member,fact_order"` |

### 2.3 时间窗口参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--window-start` | 固定窗口开始时间 | 当前时间 - 24h |
| `--window-end` | 固定窗口结束时间 | 当前时间 |
| `--window-split` | 窗口切分粒度 | `none`（可选 `day` / `week` / `month`） |
| `--window-split-unit` | 窗口切分单位（与 `--window-split` 等效） | `none` / `day` / `week` / `month` |
| `--window-split-days` | 按天切分时的步长 | `1`（可设为 10、30 等） |
| `--window-compensation-hours` | 窗口前后补偿小时数 | `0` |
| `--lookback-hours` | 回溯小时数 | `24` |
| `--overlap-seconds` | 冗余秒数（窗口重叠） | `3600` |
| `--force-window-override` | 强制使用指定窗口，不走游标兜底 | 关闭 |
| `--force-full` | 强制全量重跑，忽略游标 | 关闭 |

### 2.4 数据源参数

| 参数 | 说明 | 可选值 |
|------|------|--------|
| `--data-source` | 数据源模式 | `online`（仅 API 抓取）/ `offline`（仅本地入库）/ `hybrid`（抓取+入库） |
| `--fetch-root` | 抓取 JSON 输出根目录 | 默认 `export/JSON` |
| `--ingest-source` | 本地清洗入库源目录 | — |

> `--pipeline-flow` 已弃用，请使用 `--data-source` 替代。映射关系：`FULL` → `hybrid`，`FETCH_ONLY` → `online`，`INGEST_ONLY` → `offline`。

## 3. Flow 定义

> 术语说明：**Connector**（数据源连接器）指对接的上游 SaaS 平台（如飞球）；**Flow**（执行流程）指 ETL 任务的处理链路。CLI 参数 `--flow` 传递 Flow ID（`--pipeline` 作为已弃用别名保留），`--layers` 支持自由组合层级。

每个 Flow 包含一组按顺序执行的 ETL 层：

| Flow 名称 | 包含层 | 典型用途 |
|----------|--------|----------|
| `api_ods` | ODS | 仅从 API 抓取原始数据 |
| `api_ods_dwd` | ODS → DWD | 抓取并清洗至明细层 |
| `api_full` | ODS → DWD → DWS → INDEX | 全流程（抓取→清洗→汇总→指数） |
| `ods_dwd` | DWD | 从 ODS 清洗至 DWD（不抓取） |
| `dwd_dws` | DWS | 从 DWD 汇总至 DWS |
| `dwd_dws_index` | DWS → INDEX | 汇总并计算指数 |
| `dwd_index` | INDEX | 仅计算指数 |

## 4. 处理模式

| 模式 | 说明 |
|------|------|
| `increment_only` | 仅执行增量 ETL（默认） |
| `verify_only` | 跳过增量，仅执行校验并修复 |
| `increment_verify` | 先增量 ETL，再校验并修复 |

校验模式下可配合 `--fetch-before-verify` 先从 API 获取最新数据再校验。

## 5. 常用命令示例

```bash
# 日常增量：全流程 Flow
python -m cli.main --flow api_full --store-id 1

# 仅抓取 ODS 数据
python -m cli.main --flow api_ods --store-id 1

# 使用 --layers 自由组合
python -m cli.main --layers ODS,DWD --store-id 1

# 指定任务模式
python -m cli.main --tasks ODS_MEMBER,ODS_ORDER --store-id 1

# 校验并修复（先获取 API 数据）
python -m cli.main --flow api_full --processing-mode verify_only --fetch-before-verify

# 增量 + 校验
python -m cli.main --flow api_full --processing-mode increment_verify

# 指定时间窗口
python -m cli.main --flow api_ods --window-start "2026-02-01" --window-end "2026-02-02"

# 按天切分窗口
python -m cli.main --flow api_full --window-split day --window-split-days 10

# 试运行
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
```

## 6. 定时任务配置

### 6.1 使用系统定时任务

Linux（crontab）示例：

```cron
# 每天凌晨 4:00 执行全流程增量
0 4 * * * cd /path/to/etl-billiards && .venv/bin/python -m cli.main --flow api_full --store-id 1 >> /var/log/etl.log 2>&1
```

Windows（任务计划程序）示例：

```
程序：C:\path\to\etl-billiards\.venv\Scripts\python.exe
参数：-m cli.main --flow api_full --store-id 1
起始于：C:\path\to\etl-billiards
```

### 6.2 闲时窗口

系统支持闲时窗口配置，在闲时使用更大的时间窗口以减少 API 调用频率：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `run.idle_window.start` | `04:00` | 闲时开始 |
| `run.idle_window.end` | `16:00` | 闲时结束 |
| `run.window_minutes.default_busy` | `30` | 忙时窗口（分钟） |
| `run.window_minutes.default_idle` | `180` | 闲时窗口（分钟） |

CLI 参数覆盖：`--idle-start "04:00" --idle-end "16:00"`

## 7. 游标与增量机制

系统通过 `CursorManager` 管理每个任务的增量水位（游标）：

- 每个任务 + 门店组合维护独立的游标记录
- 游标存储在 `meta` Schema 中
- 每次成功执行后，游标自动推进到当前窗口结束时间
- `--force-window-override` 可强制使用指定窗口，绕过游标
- `--allow-empty-advance` 允许空结果时仍推进游标

`RunTracker` 记录每次运行的状态、计数和耗时，用于运行历史追溯。