改 相对路径 完成客户端

README.md

@@ -110,9 +110,6 @@ python -m cli.main \
 - `run_etl.sh`：Linux/macOS 启动脚本（需先 `cd etl_billiards`；会加载当前目录 `.env`）。
 
 ### app/
-- `app/etl_busy.py`：忙时 ETL 示例函数（TODO，占位）。
-- `app/etl_idle.py`：闲时 ETL 示例函数（TODO，占位）。
-- `app/runner.py`：简易 Runner：按 `--mode busy/idle` 调用 `app/etl_busy.py` 或 `app/etl_idle.py`（示例/未接入主 ETL）。
 
 ### etl_billiards/
 - `etl_billiards/.env`：本地运行环境变量（含敏感信息，勿提交/勿外传）。
@@ -220,13 +217,12 @@ python -m cli.main \
 - `etl_billiards/scripts/bootstrap_schema.py`：Apply the PRD-aligned warehouse schema (ODS/DWD/DWS) to PostgreSQL.
 - `etl_billiards/scripts/build_dwd_from_ods.py`：Populate PRD DWD tables from ODS payload snapshots.
 - `etl_billiards/scripts/build_dws_order_summary.py`：Recompute billiards_dws.dws_order_summary from DWD fact tables.
-- `etl_billiards/scripts/check_ods_json_vs_table.py`：ODS JSON 字段核对脚本：对照当前数据库中的 ODS 表字段，检查示例 JSON（默认目录 C:\dev\LLTQ\export\test-json-doc）
+- `etl_billiards/scripts/check_ods_json_vs_table.py`：ODS JSON 字段核对脚本：对照当前数据库中的 ODS 表字段，检查示例 JSON（默认目录 export/test-json-doc）
 - `etl_billiards/scripts/check_ods_gaps.py`：ODS 缺失校验脚本：API 主键 vs ODS 主键逐条比对，输出缺失明细样例。
 - `etl_billiards/scripts/reload_ods_windowed.py`：ODS 窗口化补跑脚本：按时间切片重跑 ODS 任务，并可配置窗口粒度与延时。
 - `etl_billiards/scripts/rebuild_db_and_run_ods_to_dwd.py`：一键重建 ETL 相关 Schema，并执行 ODS → DWD。
 - `etl_billiards/scripts/rebuild_ods_from_json.py`：从本地 JSON 示例目录重建 billiards_ods.* 表，并导入样例数据。
 - `etl_billiards/scripts/run_tests.py`：灵活的测试执行脚本，可像搭积木一样组合不同参数或预置命令（模式/数据库/归档路径等），
-- `etl_billiards/scripts/Temp1.py`：空 Python 文件（占位/临时）。
 - `etl_billiards/scripts/test_db_connection.py`：Quick utility for validating PostgreSQL connectivity (ASCII-only output).
 - `etl_billiards/scripts/test_presets.py`：测试命令仓库：集中维护 run_tests.py 的常用组合，支持一键执行。
 
@@ -388,6 +384,33 @@ python -m cli.main --pg-dsn "postgresql://user:pwd@host:5432/db" --store-id 123
 python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
 ```
 
+## 窗口切分与补偿
+用于 ETL 任务、ODS 缺失校验、数据一致性检查等“带时间窗口”的执行场景。逻辑如下：
+- 仅当传入窗口参数（如 CLI `--window-start/--window-end` 或脚本 `--start/--end`）时启用切分。
+- 先对整体窗口前后补偿 N 小时，再按月切分（`month` 为最大单位）。不需要切分时设为 `none`。
+- 分段窗口将依次执行并汇总结果。
+
+配置项（默认值见 `config/defaults.py`）：
+- `run.window_split.unit`：`month` / `none`（默认 `month`）
+- `run.window_split.compensation_hours`：整数小时（默认 2）
+
+环境变量：
+- `WINDOW_SPLIT_UNIT`
+- `WINDOW_COMPENSATION_HOURS`
+
+CLI 参数（覆盖配置）：
+- `python -m cli.main`：`--window-split-unit`，`--window-compensation-hours`
+- `scripts/check_ods_gaps.py`：`--window-split-unit`，`--window-compensation-hours`
+- `scripts/check_data_integrity.py`：`--window-split-unit`，`--window-compensation-hours`
+- `scripts/reload_ods_windowed.py`：`--window-split-unit`，`--window-compensation-hours`
+
+示例（`unit=month`，`compensation_hours=2`）：
+- 传入窗口：`2025/11/10 10:00` - `2026/1/19 10:15`
+- 实际处理窗口切分：
+  - `2025/11/10 08:00` - `2025/12/01 00:00`
+  - `2025/12/01 00:00` - `2026/01/01 00:00`
+  - `2026/01/01 00:00` - `2026/01/19 12:15`
+
 ## 测试
 说明：仓库未固定 pytest 版本（运行测试需自行安装 `pytest`）。
 
@@ -419,7 +442,7 @@ python scripts/test_db_connection.py --dsn "postgresql://user:pwd@host:5432/db"
 - 离线回放/重建 ODS（开发/运维）：  
   ```bash
   cd etl_billiards
-  python scripts/rebuild_ods_from_json.py --dsn "$PG_DSN" --json-dir "C:\\path\\to\\json-doc"
+  python scripts/rebuild_ods_from_json.py --dsn "$PG_DSN" --json-dir "export/test-json-doc"
   ```
 
 ## ODS 表概览（数据路径）
@@ -584,10 +607,10 @@ python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_BUILD_ORDER_SUMMARY
 - `--log-level` 日志级别（`INFO`/`DEBUG`）。
 - `--no-log-console` 禁用控制台日志记录（仅写入文件）。
 
-示例（按桌、按天设置窗口）：
+示例（按月切分 + 前后补偿 2h）：
 ```bash
 cd etl_billiards
-python scripts/check_ods_gaps.py --start 2025-07-01 --window-days 1 --task-codes ODS_PAYMENT --sleep-per-window-seconds 0.5
-python scripts/reload_ods_windowed.py --tasks ODS_PAYMENT,ODS_TABLE_USE --start 2025-07-01 --window-days 1 --sleep-seconds 1
+python scripts/check_ods_gaps.py --start 2025-07-01 --end 2025-09-30 --window-split-unit month --window-compensation-hours 2 --task-codes ODS_PAYMENT --sleep-per-window-seconds 0.5
+python scripts/reload_ods_windowed.py --tasks ODS_PAYMENT,ODS_TABLE_USE --start 2025-07-01 --end 2025-09-30 --window-split-unit month --window-compensation-hours 2 --sleep-seconds 1
 python run_update.py --check-ods-gaps --check-ods-window-days 1 --check-ods-sleep-per-window-seconds 0.5
-```
+```