init: 项目初始提交 - NeoZQYY Monorepo 完整代码

apps/etl/pipelines/feiqiu/docs/operations/scheduling.md

@@ -0,0 +1,152 @@
+# 调度配置说明
+
+## 1. 运行模式概览
+
+系统支持两种运行模式：
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| **任务模式** | 通过 `--tasks` 指定具体任务代码 | 单任务调试、手动补数 |
+| **管道模式** | 通过 `--pipeline` 指定管道类型 | 日常增量、全流程运行 |
+
+## 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 管道参数
+
+| 参数 | 说明 | 可选值 |
+|------|------|--------|
+| `--pipeline` | 管道类型 | 见下方管道定义表 |
+| `--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`） |
+| `--lookback-hours` | 回溯小时数 | `24` |
+| `--overlap-seconds` | 冗余秒数（窗口重叠） | `3600` |
+| `--force-window-override` | 强制使用指定窗口，不走游标兜底 | 关闭 |
+
+### 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. 管道定义
+
+每个管道包含一组按顺序执行的 ETL 层：
+
+| 管道名称 | 包含层 | 典型用途 |
+|----------|--------|----------|
+| `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
+# 日常增量：全流程管道
+python -m cli.main --pipeline api_full --store-id 1
+
+# 仅抓取 ODS 数据
+python -m cli.main --pipeline api_ods --store-id 1
+
+# 指定任务模式
+python -m cli.main --tasks ODS_MEMBER,ODS_ORDER --store-id 1
+
+# 校验并修复（先获取 API 数据）
+python -m cli.main --pipeline api_full --processing-mode verify_only --fetch-before-verify
+
+# 增量 + 校验
+python -m cli.main --pipeline api_full --processing-mode increment_verify
+
+# 指定时间窗口
+python -m cli.main --pipeline api_ods --window-start "2026-02-01" --window-end "2026-02-02"
+
+# 按天切分窗口
+python -m cli.main --pipeline 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 --pipeline api_full --store-id 1 >> /var/log/etl.log 2>&1
+```
+
+Windows（任务计划程序）示例：
+
+```
+程序：C:\path\to\etl-billiards\.venv\Scripts\python.exe
+参数：-m cli.main --pipeline 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` 管理每个任务的增量水位（游标）：
+
+- 每个任务 + 门店组合维护独立的游标记录
+- 游标存储在 `etl_admin` Schema 中
+- 每次成功执行后，游标自动推进到当前窗口结束时间
+- `--force-window-override` 可强制使用指定窗口，绕过游标
+- `--allow-empty-advance` 允许空结果时仍推进游标
+
+`RunTracker` 记录每次运行的状态、计数和耗时，用于运行历史追溯。