Neo-ZQYY/apps/etl/connectors/feiqiu/docs/operations/scheduling.md

调度配置说明

1. 运行模式概览

系统支持两种运行模式：

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

2. CLI 参数详解

2.1 基本参数

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. 常用命令示例

# 日常增量：全流程 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）示例：

# 每天凌晨 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 记录每次运行的状态、计数和耗时，用于运行历史追溯。