# 飞球 ETL 系统（ODS → DWD）

面向门店业务的 ETL：从上游 API 或离线 JSON 采集订单、支付、会员、库存等数据，先落地 **ODS**，再清洗装载 **DWD**（含 SCD2 维度、事实增量），并输出质量校验报表。

## 快速运行（离线示例 JSON）
> 以下命令默认在 `etl_billiards/` 目录执行（项目会从 `etl_billiards/.env` 读取配置；也可直接设置环境变量）。

1) 环境：Python 3.10+、PostgreSQL。
2) 配置：编辑 `etl_billiards/.env`（或设环境变量），至少包含：
   ```env
   STORE_ID=123
   PG_DSN=postgresql://<user>:<password>@<host>:<port>/<db>
   # 示例：使用仓库内置的最小样例（仅 1 个 JSON）
   INGEST_SOURCE_DIR=../tmp/single_ingest
   ```
3) 安装依赖：
   ```bash
   cd etl_billiards
   pip install -r requirements.txt
   ```
4) 回放入库（ODS）→ 装载 DWD → 质检（可用 `--ingest-source` 覆盖 `INGEST_SOURCE_DIR`）：
   ```bash
   python -m cli.main --pipeline-flow INGEST_ONLY --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA
   python -m cli.main --pipeline-flow INGEST_ONLY --tasks MANUAL_INGEST --ingest-source "../tmp/single_ingest"
   python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWD_LOAD_FROM_ODS
   python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWD_QUALITY_CHECK
   # 报表：reports/dwd_quality_report.json
   ```

> 可按需单独运行：  
> - 仅建表：`python -m cli.main --tasks INIT_ODS_SCHEMA`  
> - 仅 ODS 灌入：`python -m cli.main --tasks MANUAL_INGEST`  
> - 仅 DWD 装载：`python -m cli.main --tasks INIT_DWD_SCHEMA,DWD_LOAD_FROM_ODS`

> Windows：可用 `etl_billiards/run_ods.bat` 一键执行 ODS 建表 + 灌入示例 JSON（`INIT_ODS_SCHEMA` + `MANUAL_INGEST`）。

## 正式环境（在线抓取 → 更新 ODS → 更新 DWD）

**核心入口 CLI（推荐在 `etl_billiards/` 目录执行）**
- `python -m cli.main`

### 必备配置（建议通过环境变量或 `.env`）
- 数据库：`PG_DSN`、`STORE_ID`
- 在线抓取：`API_TOKEN`（可选 `API_BASE`、`API_TIMEOUT`、`API_PAGE_SIZE`、`API_RETRY_MAX`）
- 输出目录（可选）：`EXPORT_ROOT`、`LOG_ROOT`、`FETCH_ROOT`/`JSON_FETCH_ROOT`

**安全提示**：建议将数据库/Token 等凭证保存在 `.env` 或受控秘钥管理中，生产环境使用最小权限账号。

### 推荐定时方式 A（两段定时，更清晰）
1) **更新 ODS（在线抓取 + 入库，FULL）**
   ```bash
   python -m cli.main \
     --pipeline-flow FULL \
     --tasks PRODUCTS,TABLES,MEMBERS,ASSISTANTS,PACKAGES_DEF,ORDERS,PAYMENTS,REFUNDS,COUPON_USAGE,INVENTORY_CHANGE,TOPUPS,TABLE_DISCOUNT,ASSISTANT_ABOLISH,LEDGER \
     --pg-dsn "$PG_DSN" --store-id "$STORE_ID" \
     --api-token "$API_TOKEN"
   ```
2) **ODS → DWD（将新增/变更同步到 DWD）**
   ```bash
   python -m cli.main \
     --pipeline-flow INGEST_ONLY \
     --tasks DWD_LOAD_FROM_ODS \
     --pg-dsn "$PG_DSN" --store-id "$STORE_ID"
   ```

### 推荐定时方式 B（一条命令串起来）
同一条命令先跑在线抓取/入库任务，再跑 DWD 装载任务：
```bash
python -m cli.main \
  --pipeline-flow FULL \
  --tasks PRODUCTS,TABLES,MEMBERS,ASSISTANTS,PACKAGES_DEF,ORDERS,PAYMENTS,REFUNDS,COUPON_USAGE,INVENTORY_CHANGE,TOPUPS,TABLE_DISCOUNT,ASSISTANT_ABOLISH,LEDGER,DWD_LOAD_FROM_ODS \
  --pg-dsn "$PG_DSN" --store-id "$STORE_ID" \
  --api-token "$API_TOKEN"
```

### `pipeline-flow` 说明
- `FULL`：在线抓取落盘 + 本地清洗入库（ODS 任务会走抓取；`DWD_LOAD_FROM_ODS` 仅走入库阶段）
- `FETCH_ONLY`：仅在线抓取落盘，不入库
- `INGEST_ONLY`：仅从本地 JSON 回放入库（适合离线回放/补跑）

## 目录结构与关键文件
- 仓库根目录：`etl_billiards/` 主代码；`app/` 示例 runner；`开发笔记/` 项目笔记；`tmp/` 草稿/调试归档；`requirements.txt`（仓库根）依赖；`run_etl.sh/.bat` 启动脚本。  
  - 注意：根目录的 `run_etl.sh/.bat` 运行时要求当前目录为 `etl_billiards/`（因为入口是 `python -m cli.main`）。
- `etl_billiards/`（主代码目录）
  - `.env`：本地配置文件（可选，用环境变量也可）
  - `cli/`：CLI 入口（`cli/main.py`）
  - `config/`：`defaults.py` 默认值；`env_parser.py` 解析 `.env`/环境变量；`settings.py` AppConfig 加载/校验
  - `api/`：`client.py` HTTP 请求、重试、分页与落盘
  - `database/`：`connection.py` 连接封装；`operations.py` 批量 upsert；DDL：`schema_ODS_doc.sql`、`schema_dwd_doc.sql`
  - `tasks/`：业务任务（ODS 抓取/回放、DWD 装载、质检等）
  - `loaders/`：ODS/DWD/SCD2 Loader 实现
  - `scd/`：`scd2_handler.py`（维度 SCD2 历史）
  - `quality/`：质量检查器（行数/金额对照）
  - `orchestration/`：`scheduler.py` 调度；`task_registry.py` 注册；`cursor_manager.py` 水位管理；`run_tracker.py` 运行记录
  - `scripts/`：重建/测试/探活工具
  - `docs/`：映射/样例/质检说明文档
  - `fetch-test/`：接口联调/规则验证的一次性脚本与报告（不影响主流程）
  - `reports/`：质检输出（如 `dwd_quality_report.json`）
  - `tests/`：单元/集成测试

## 项目文件索引（维护/AI 快速定位）
> 说明：用于维护/AI 快速定位文件路径与用途；默认不列出 `.git/`、`__pycache__/`、`.pytest_cache/`、`*.pyc` 等自动生成内容。

### /
- `.gitignore`：Git 忽略规则。
- `.gitkeep`：占位文件（用于保留空目录）。
- `README.md`：项目总览与使用说明（本文档）。
- `requirements.txt`：仓库根依赖清单（不含版本约束，建议优先用 `etl_billiards/requirements.txt`）。
- `run_etl.bat`：Windows 启动脚本（需先 `cd etl_billiards`；入口为 `python -m cli.main`）。
- `run_etl.sh`：Linux/macOS 启动脚本（需先 `cd etl_billiards`；会加载当前目录 `.env`）。

### app/

### etl_billiards/
- `etl_billiards/.env`：本地运行环境变量（含敏感信息，勿提交/勿外传）。
- `etl_billiards/__init__.py`：Python 包标记文件。
- `etl_billiards/ods_row_report.json`：ODS 行数对照报告（source json vs ODS 表）。
- `etl_billiards/requirements.txt`：ETL 运行依赖（带最低版本约束）。
- `etl_billiards/run_ods.bat`：Windows 一键脚本：重建 ODS 并灌入示例 JSON。
- `etl_billiards/setup.py`：打包/安装脚本（当前项目主要按“`cd etl_billiards; python -m cli.main`”方式运行）。

### etl_billiards/api/
- `etl_billiards/api/__init__.py`：Python 包标记文件。
- `etl_billiards/api/client.py`：API客户端：统一封装 POST/重试/分页与列表提取逻辑。
- `etl_billiards/api/endpoint_routing.py`：“近期记录 / 历史记录(Former)”接口路由规则。
- `etl_billiards/api/local_json_client.py`：本地 JSON 客户端，模拟 APIClient 的分页接口，从落盘的 JSON 回放数据。
- `etl_billiards/api/recording_client.py`：包装 APIClient，将分页响应落盘便于后续本地清洗。

### etl_billiards/cli/
- `etl_billiards/cli/__init__.py`：Python 包标记文件。
- `etl_billiards/cli/main.py`：CLI主入口

### etl_billiards/config/
- `etl_billiards/config/__init__.py`：Python 包标记文件。
- `etl_billiards/config/defaults.py`：配置默认值定义
- `etl_billiards/config/env_parser.py`：环境变量解析
- `etl_billiards/config/settings.py`：配置管理主类

### etl_billiards/database/
- `etl_billiards/database/__init__.py`：Python 包标记文件。
- `etl_billiards/database/base.py`：数据库操作（批量、RETURNING支持）
- `etl_billiards/database/connection.py`：Database connection manager with capped connect_timeout.
- `etl_billiards/database/operations.py`：数据库批量操作
- `etl_billiards/database/schema_dwd_doc.sql`：DWD Schema DDL（含字段/注释/口径说明）。
- `etl_billiards/database/schema_etl_admin.sql`：etl_admin 元数据 Schema DDL（任务/水位/运行记录等）。
- `etl_billiards/database/schema_ODS_doc.sql`：ODS Schema DDL（含字段/注释/口径说明）。
- `etl_billiards/database/seed_ods_tasks.sql`：SQL 种子脚本：初始化/注册 ODS 任务。
- `etl_billiards/database/seed_scheduler_tasks.sql`：SQL 种子脚本：初始化调度任务配置。

### etl_billiards/database/Deleded & backup/
- （本目录无直接文件）

### etl_billiards/docs/
- `etl_billiards/docs/dwd_main_tables_dictionary.md`：DWD 主表（非 Ex）表格说明书
- `etl_billiards/docs/在线抓取，更新ODS ，然后将更新的ODS内容，对应到DWD的更新。.md`：在线抓取，更新ODS ，然后将更新的ODS内容，对应到DWD的更新。

### etl_billiards/fetch-test/
- `etl_billiards/fetch-test/compare_recent_former_endpoints.py`：对比“近期记录”与“历史记录(Former)”接口：
- `etl_billiards/fetch-test/README.md`：fetch-test
- `etl_billiards/fetch-test/recent_vs_former_report.json`：报告/比对输出（JSON）。
- `etl_billiards/fetch-test/recent_vs_former_report.md`：近期记录 vs 历史记录(Former) 接口对比报告

### etl_billiards/loaders/
- `etl_billiards/loaders/__init__.py`：Python 包标记文件。
- `etl_billiards/loaders/base_loader.py`：数据加载器基类

### etl_billiards/loaders/dimensions/
- `etl_billiards/loaders/dimensions/__init__.py`：Python 包标记文件。
- `etl_billiards/loaders/dimensions/assistant.py`：助教维度加载器
- `etl_billiards/loaders/dimensions/member.py`：会员维度表加载器
- `etl_billiards/loaders/dimensions/package.py`：团购/套餐定义加载器
- `etl_billiards/loaders/dimensions/product.py`：商品维度 + 价格SCD2 加载器
- `etl_billiards/loaders/dimensions/table.py`：台桌维度加载器

### etl_billiards/loaders/facts/
- `etl_billiards/loaders/facts/__init__.py`：Python 包标记文件。
- `etl_billiards/loaders/facts/assistant_abolish.py`：助教作废事实表
- `etl_billiards/loaders/facts/assistant_ledger.py`：助教流水事实表
- `etl_billiards/loaders/facts/coupon_usage.py`：券核销事实表
- `etl_billiards/loaders/facts/inventory_change.py`：库存变动事实表
- `etl_billiards/loaders/facts/order.py`：订单事实表加载器
- `etl_billiards/loaders/facts/payment.py`：支付事实表加载器
- `etl_billiards/loaders/facts/refund.py`：退款事实表加载器
- `etl_billiards/loaders/facts/table_discount.py`：台费打折事实表
- `etl_billiards/loaders/facts/ticket.py`：小票详情加载器
- `etl_billiards/loaders/facts/topup.py`：充值记录事实表

### etl_billiards/loaders/ods/
- `etl_billiards/loaders/ods/__init__.py`：Python 包标记文件。
- `etl_billiards/loaders/ods/generic.py`：Generic ODS loader that keeps raw payload + primary keys.

### etl_billiards/models/
- `etl_billiards/models/__init__.py`：Python 包标记文件。
- `etl_billiards/models/parsers.py`：数据类型解析器
- `etl_billiards/models/validators.py`：数据验证器

### etl_billiards/orchestration/
- `etl_billiards/orchestration/__init__.py`：Python 包标记文件。
- `etl_billiards/orchestration/cursor_manager.py`：游标管理器
- `etl_billiards/orchestration/run_tracker.py`：运行记录追踪器
- `etl_billiards/orchestration/scheduler.py`：ETL 调度：支持在线抓取、离线清洗入库、全流程三种模式。
- `etl_billiards/orchestration/task_registry.py`：任务注册表

### etl_billiards/quality/
- `etl_billiards/quality/__init__.py`：Python 包标记文件。
- `etl_billiards/quality/balance_checker.py`：余额一致性检查器
- `etl_billiards/quality/base_checker.py`：数据质量检查器基类

### etl_billiards/reports/
- `etl_billiards/reports/dwd_quality_report.json`：DWD 质量核对输出（行数/金额对照）。

### etl_billiards/scd/
- `etl_billiards/scd/__init__.py`：Python 包标记文件。
- `etl_billiards/scd/scd2_handler.py`：SCD2 (Slowly Changing Dimension Type 2) 处理逻辑

### etl_billiards/scripts/
- `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（默认目录 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/test_db_connection.py`：Quick utility for validating PostgreSQL connectivity (ASCII-only output).
- `etl_billiards/scripts/test_presets.py`：测试命令仓库：集中维护 run_tests.py 的常用组合，支持一键执行。

### etl_billiards/scripts/Deleded & backup/
- （本目录无直接文件）

### etl_billiards/tasks/
- `etl_billiards/tasks/__init__.py`：Python 包标记文件。
- `etl_billiards/tasks/assistant_abolish_task.py`：助教作废任务
- `etl_billiards/tasks/assistants_task.py`：助教账号任务
- `etl_billiards/tasks/base_dwd_task.py`：DWD任务基类
- `etl_billiards/tasks/base_task.py`：ETL任务基类（引入 Extract/Transform/Load 模板方法）
- `etl_billiards/tasks/coupon_usage_task.py`：平台券核销任务
- `etl_billiards/tasks/dwd_load_task.py`：DWD 装载任务：从 ODS 增量写入 DWD（维度 SCD2，事实按时间增量）。
- `etl_billiards/tasks/dwd_quality_task.py`：DWD 质量核对任务：按 dwd_quality_check.md 输出行数/金额对照报表。
- `etl_billiards/tasks/init_dwd_schema_task.py`：初始化 DWD Schema：执行 schema_dwd_doc.sql，可选先 DROP SCHEMA。
- `etl_billiards/tasks/init_schema_task.py`：任务：初始化运行环境，执行 ODS 与 etl_admin 的 DDL，并准备日志/导出目录。
- `etl_billiards/tasks/inventory_change_task.py`：库存变更任务
- `etl_billiards/tasks/ledger_task.py`：助教流水任务
- `etl_billiards/tasks/manual_ingest_task.py`：手工示例数据灌入：按 schema_ODS_doc.sql 的表结构写入 ODS。
- `etl_billiards/tasks/members_dwd_task.py`：DWD Task：Process Member Records from ODS to Dimension Table.
- `etl_billiards/tasks/members_task.py`：会员ETL任务
- `etl_billiards/tasks/ods_json_archive_task.py`：在线抓取 ODS 相关接口并落盘为 JSON（用于后续离线回放/入库）。
- `etl_billiards/tasks/ods_tasks.py`：ODS ingestion tasks.
- `etl_billiards/tasks/orders_task.py`：订单ETL任务
- `etl_billiards/tasks/packages_task.py`：团购/套餐定义任务
- `etl_billiards/tasks/payments_dwd_task.py`：DWD Task：Process Payment Records from ODS to Fact Table.
- `etl_billiards/tasks/payments_task.py`：支付记录ETL任务
- `etl_billiards/tasks/products_task.py`：商品档案（PRODUCTS）ETL任务
- `etl_billiards/tasks/refunds_task.py`：退款记录任务
- `etl_billiards/tasks/table_discount_task.py`：台费折扣任务
- `etl_billiards/tasks/tables_task.py`：台桌档案任务
- `etl_billiards/tasks/ticket_dwd_task.py`：DWD Task：Process Ticket Details from ODS to DWD fact tables.
- `etl_billiards/tasks/topups_task.py`：充值记录任务

### etl_billiards/tasks/dwd/
- （本目录无直接文件）

### etl_billiards/tests/
- `etl_billiards/tests/__init__.py`：Python 包标记文件。

### etl_billiards/tests/integration/
- `etl_billiards/tests/integration/__init__.py`：Python 包标记文件。
- `etl_billiards/tests/integration/test_database.py`：数据库集成测试

### etl_billiards/tests/unit/
- `etl_billiards/tests/unit/__init__.py`：Python 包标记文件。
- `etl_billiards/tests/unit/task_test_utils.py`：ETL 任务测试的共用辅助模块，涵盖在线/离线模式所需的伪造数据、客户端与配置等工具函数。
- `etl_billiards/tests/unit/test_config.py`：配置管理测试
- `etl_billiards/tests/unit/test_endpoint_routing.py`：Unit tests for recent/former endpoint routing.
- `etl_billiards/tests/unit/test_etl_tasks_offline.py`：离线模式任务测试，通过回放归档 JSON 来验证 T+L 链路可用。
- `etl_billiards/tests/unit/test_etl_tasks_online.py`：在线模式下的端到端任务测试，验证所有任务在模拟 API 下能顺利执行。
- `etl_billiards/tests/unit/test_etl_tasks_stages.py`：验证 14 个任务的 E/T/L 分阶段调用（FakeDB/FakeAPI，不访问真实接口或数据库）。
- `etl_billiards/tests/unit/test_ods_tasks.py`：Unit tests for the new ODS ingestion tasks.
- `etl_billiards/tests/unit/test_parsers.py`：解析器测试
- `etl_billiards/tests/unit/test_reporting.py`：汇总与报告工具的单测。

### etl_billiards/utils/
- `etl_billiards/utils/__init__.py`：Python 包标记文件。
- `etl_billiards/utils/helpers.py`：通用工具函数
- `etl_billiards/utils/json_store.py`：JSON 归档/读取的通用工具。
- `etl_billiards/utils/reporting.py`：简单的任务结果汇总与格式化工具。

### tmp/
- `tmp/20251121-task.txt`：历史任务/计划记录（可能存在编码问题）。
- `tmp/doc_extracted.txt`：从 DWD 文档抽取的正文（大文本）。
- `tmp/doc_lines.txt`：DWD 文档按行抽取/对照（文本）。
- `tmp/dwd_tables.json`：DWD 表清单（JSON）。
- `tmp/dwd_tables_full.json`：DWD 表清单（完整版 JSON）。
- `tmp/hebing.py`：临时脚本：按“同名 key”合并目录内 md+json 输出 merged_output.txt。
- `tmp/README_FULL.md`：历史/草稿：README 详细版（已合并进根 README）。
- `tmp/rebuild_run_20251214-042115.log`：运行日志/调试输出（临时文件）。
- `tmp/rewrite_schema_dwd_doc_comments.py`：临时脚本：批量重写 DWD DDL 注释（归档/草稿）。
- `tmp/rewrite_schema_ods_doc_comments.py`：临时脚本：批量重写 ODS DDL 注释（归档/草稿）。
- `tmp/schema_dwd.sql`：DWD schema 草稿/导出（归档）。
- `tmp/schema_dwd_doc.sql`：DWD schema doc 版本（归档）。
- `tmp/schema_ODS_doc copy.sql`：ODS schema doc 备份（归档）。
- `tmp/schema_ODS_doc.sql`：ODS schema doc 版本（归档）。
- `tmp/temp_chinese.txt`：编码/文本对照测试。
- `tmp/tmp_debug_sql.py`：临时脚本：调试 SQL/映射（归档）。
- `tmp/tmp_drop_dwd.py`：临时脚本：DROP SCHEMA billiards_dwd（危险，勿在生产执行）。
- `tmp/tmp_dwd_tasks.py`：临时脚本：调试 DWD 相关任务（归档）。
- `tmp/tmp_problems.py`：临时脚本：问题排查记录/复现（归档）。
- `tmp/tmp_run_sql.py`：临时脚本：拼接/执行一条 INSERT...SELECT 验证映射（需 PG_DSN）。
- `tmp/非球接口API.md`：上游接口笔记/汇总（草稿/归档）。

### tmp/a/
- （本目录无直接文件）

### tmp/b/
- （本目录无直接文件）

### tmp/etl_billiards_misc/
- `tmp/etl_billiards_misc/0.py`：Simple PostgreSQL connectivity smoke-checker.
- `tmp/etl_billiards_misc/feiqiu-ETL.code-workspace`：VS Code workspace 文件（归档）。
- `tmp/etl_billiards_misc/草稿.txt`：草稿/说明（归档）。

### tmp/etl_billiards_misc/backups/
- `tmp/etl_billiards_misc/backups/manual_ingest_task.py`：历史版本备份（归档）。
- `tmp/etl_billiards_misc/backups/manual_ingest_task.py.bak_20251209`：历史版本备份（归档）。
- `tmp/etl_billiards_misc/backups/schema_ODS_doc.sql`：历史版本备份（归档）。
- `tmp/etl_billiards_misc/backups/schema_ODS_doc.sql.bak_20251209`：历史版本备份（归档）。

### tmp/etl_billiards_misc/tmp & Delete/
- `tmp/etl_billiards_misc/tmp & Delete/.env.example`：旧示例配置（归档）。
- `tmp/etl_billiards_misc/tmp & Delete/dwd_schema_columns.txt`：DWD 字段提取/对照文本（归档）。
- `tmp/etl_billiards_misc/tmp & Delete/DWD层设计建议.docx`：DWD 设计建议文档（归档）。
- `tmp/etl_billiards_misc/tmp & Delete/DWD层设计草稿.md`：DWD 设计草稿（归档）。
- `tmp/etl_billiards_misc/tmp & Delete/schema_dwd_doc.sql.bak`：schema 备份（归档）。
- `tmp/etl_billiards_misc/tmp & Delete/schema_ODS_doc.sql.bak`：schema 备份（归档）。
- `tmp/etl_billiards_misc/tmp & Delete/schema_ODS_doc.sql.rewrite2.bak`：schema 重写过程备份（归档）。
- `tmp/etl_billiards_misc/tmp & Delete/schema_v2.sql`：schema v2 草稿（归档）。

### tmp/recharge_only/
- `tmp/recharge_only/recharge_settlements.json`：离线样例 JSON（仅充值结算）。

### tmp/single_ingest/
- `tmp/single_ingest/goods_stock_movements.json`：离线最小样例 JSON（单文件）。

### 开发笔记/
- `开发笔记/记录.md`：开发/迁移过程的备忘与待办（归档）。

## 架构与流程
执行链路（控制流）：
1) CLI（`cli/main.py`）解析参数 → 生成 AppConfig → 初始化日志/DB/API；  
2) 调度层（`orchestration/scheduler.py`）按 `task_registry.py` 实例化任务，设置 run_uuid、cursor（水位）、上下文；  
3) 任务执行模板：获取时间窗口/水位（`cursor_manager.py`）→ Extract（API 分页/重试或离线读 JSON）→ Transform（解析/校验）→ Load（Loader 批量 upsert/SCD2/增量写入，底层 `database/operations.py`）→（可选）质量检查 → 更新水位与运行记录（`run_tracker.py`），提交/回滚事务。

数据流与依赖：
- 配置：`config/defaults.py` + `.env`/环境变量 + CLI 参数叠加
- 在线：`api/client.py` 支撑分页/重试；可落盘 JSON（`pipeline.fetch_root`）
- 离线：`manual_ingest_task.py` 从 `INGEST_SOURCE_DIR` 回放入库
- DWD：`dwd_load_task.py` 依据 `TABLE_MAP/FACT_MAPPINGS` 映射装载，维度走 SCD2，事实走增量
- 质检：`dwd_quality_task.py` 输出 `reports/dwd_quality_report.json`

## ODS → DWD 策略与建模要点
1) ODS 留底：保留源主键、payload、时间/来源信息，便于回溯。  
2) DWD 清洗：维度走 SCD2，事实按时间/水位增量；字段类型、单位、枚举标准化，同时保留溯源字段。  
3) 颗粒一致：一张 DWD 表只承载一种业务事件/颗粒，避免混颗粒。  
4) 业务键统一：site_id、member_id、table_id、order_settle_id、order_trade_no 等统一命名。  
5) 不过度汇总：DWD 只做明细/轻度清洗，聚合留到 DWS/报表。  
6) 去嵌套：数组展开为子表/子行，重复 profile 提炼为维度。  
7) 长期演进：优先加列/加表，减少对已有表结构的破坏。

## 常用 CLI
```bash
cd etl_billiards

# 运行 defaults.py 中的默认任务列表（在线 FULL 流程）
python -m cli.main --pg-dsn "$PG_DSN" --store-id "$STORE_ID" --api-token "$API_TOKEN"

# 运行指定任务
python -m cli.main --tasks INIT_ODS_SCHEMA,MANUAL_INGEST --pipeline-flow INGEST_ONLY --ingest-source "../tmp/single_ingest"

# 覆盖 DSN / API / 输出目录
python -m cli.main --pg-dsn "postgresql://user:pwd@host:5432/db" --store-id 123 --api-token "..." --fetch-root "./json_fetch"

# 试运行（不写库）
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`）。

```bash
cd etl_billiards
pip install pytest

# 单元测试（模拟 API + FakeDB）
pytest tests/unit

# 集成测试（需要设置 TEST_DB_DSN）
TEST_DB_DSN="postgresql://user:pwd@host:5432/db" pytest tests/integration/test_database.py

# 便捷测试执行器（可选）
python scripts/run_tests.py --suite online -k ORDERS
python scripts/test_db_connection.py --dsn "postgresql://user:pwd@host:5432/db" --query "SELECT 1"
```

## 开发与扩展
- 新任务：在 `tasks/` 继承 BaseTask，实现 `get_task_code/execute`，并在 `orchestration/task_registry.py` 注册。  
- 新 Loader/Checker：参考 `loaders/`、`quality/`，复用批量 upsert/质检接口。  
- 新配置项：在 `config/defaults.py` 增加默认值，并在 `config/env_parser.py` 增加环境变量映射（如需要）。

## ODS 任务上线指引
- 元数据/任务注册脚本：
  - `etl_billiards/database/seed_ods_tasks.sql`
  - `etl_billiards/database/seed_scheduler_tasks.sql`
- 确认 `etl_admin.etl_task` 中已启用所需任务（不同环境需替换 store_id / schema）。  
- 离线回放/重建 ODS（开发/运维）：  
  ```bash
  cd etl_billiards
  python scripts/rebuild_ods_from_json.py --dsn "$PG_DSN" --json-dir "export/test-json-doc"
  ```

## ODS 表概览（数据路径）
| ODS 表名                           | 接口 Path                                         | 数据列表路径                  |
| ---------------------------------- | ------------------------------------------------- | ----------------------------- |
| assistant_accounts_master          | /PersonnelManagement/SearchAssistantInfo          | data.assistantInfos           |
| assistant_service_records          | /AssistantPerformance/GetOrderAssistantDetails    | data.orderAssistantDetails    |
| assistant_cancellation_records     | /AssistantPerformance/GetAbolitionAssistant       | data.abolitionAssistants      |
| goods_stock_movements              | /GoodsStockManage/QueryGoodsOutboundReceipt       | data.queryDeliveryRecordsList |
| goods_stock_summary                | /TenantGoods/GetGoodsStockReport                  | data                          |
| group_buy_packages                 | /PackageCoupon/QueryPackageCouponList             | data.packageCouponList        |
| group_buy_redemption_records       | /Site/GetSiteTableUseDetails                      | data.siteTableUseDetailsList  |
| member_profiles                    | /MemberProfile/GetTenantMemberList                | data.tenantMemberInfos        |
| member_balance_changes             | /MemberProfile/GetMemberCardBalanceChange         | data.tenantMemberCardLogs     |
| member_stored_value_cards          | /MemberProfile/GetTenantMemberCardList            | data.tenantMemberCards        |
| payment_transactions               | /PayLog/GetPayLogListPage                         | data                          |
| platform_coupon_redemption_records | /Promotion/GetOfflineCouponConsumePageList        | data                          |
| recharge_settlements               | /Site/GetRechargeSettleList                       | data.settleList               |
| refund_transactions                | /Order/GetRefundPayLogList                        | data                          |
| settlement_records                 | /Site/GetAllOrderSettleList                       | data.settleList               |
| settlement_ticket_details          | /Order/GetOrderSettleTicketNew                    | 完整 JSON                     |
| site_tables_master                 | /Table/GetSiteTables                              | data.siteTables               |
| stock_goods_category_tree          | /TenantGoodsCategory/QueryPrimarySecondaryCategory| data.goodsCategoryList        |
| store_goods_master                 | /TenantGoods/GetGoodsInventoryList                | data.orderGoodsList           |
| store_goods_sales_records          | /TenantGoods/GetGoodsSalesList                    | data.orderGoodsLedgers        |
| table_fee_discount_records         | /Site/GetTaiFeeAdjustList                         | data.taiFeeAdjustInfos        |
| table_fee_transactions             | /Site/GetSiteTableOrderDetails                    | data.siteTableUseDetailsList  |
| tenant_goods_master                | /TenantGoods/QueryTenantGoods                     | data.tenantGoodsList          |

> 完整字段级映射见 `etl_billiards/docs/` 与 ODS/DWD DDL。

## 当前状态（2025-12-09）
- 示例 JSON 已全量灌入，DWD 行数与 ODS 对齐。  
- 分类维度已展平大类+子类：`dim_goods_category` 26 行（category_level/leaf 已赋值）。  
- 部分空字段源数据即为空，如需补值请先确认上游。

## 可精简/归档
- `tmp/`、`tmp/etl_billiards_misc/` 中草稿、旧备份、调试脚本仅供参考，不影响运行。  
- 根级保留必要文件（README、requirements、run_etl.*），其余临时文件按需归档至 `tmp/`。

## 一键更新（推荐）

日常需要把数据从 ODS 更新到最新，并同步刷新 DWD/DWS 时，直接运行一键脚本：

```bash
cd etl_billiards
python run_update.py
```

常用参数：
- `--overlap-seconds 3600`：冗余抓取窗口（默认 3600 秒）
- `--dws-rebuild-days 1`：DWS 回算冗余天数（默认 1 天）
- `--dws-start YYYY-MM-DD --dws-end YYYY-MM-DD`：手工指定 DWS 回算日期范围
- `--skip-ods`：跳过 ODS 在线抓取（仅跑 DWD/DWS）
- `--ods-tasks ODS_PAYMENT,ODS_TABLE_USE,...`：只跑指定 ODS 任务
- `--check-ods-gaps`：在 ODS 更新完成后执行缺失校验（API 主键 vs ODS 主键）
- `--check-ods-overlap-hours 24`：缺失校验时，从 ODS 最新截止时间回溯的小时数（默认 24）
- `--check-ods-window-days 1`：缺失校验 API 窗口粒度（默认 1 天）
- `--check-ods-page-size 200`：缺失校验 API 每页大小（默认 200）
- `--check-ods-timeout-sec 1800`：缺失校验步骤超时秒数（默认 1800）
- `--check-ods-task-codes ODS_PAYMENT,ODS_TABLE_USE,...`：仅校验指定 ODS 任务

### ODS 缺失校验（API vs ODS）

说明：
- 校验口径为 ODS 表 `MAX(fetched_at)` 的最小值，视为“最新一致截止时间”。  
- `--from-cutoff` 会从该截止时间回溯 N 小时（默认 24 小时）到当前，便于日常增量校验。  

全量校验（从 2025-07 至今）：
```bash
cd etl_billiards
python scripts/check_ods_gaps.py --start 2025-07-01
```

更新时校验（从 ODS 最新截止时间回溯 24h）：
```bash
cd etl_billiards
python run_update.py --check-ods-gaps
```

## FAQ
- 字段空值：若映射已存在且源列非空仍为空，再检查上游 JSON；维度 SCD2 按全量合并。  
- DSN/路径：确认 `PG_DSN`、`STORE_ID`、`INGEST_SOURCE_DIR` 与本地一致。  
- 新增任务：在 `tasks/` 实现并注册到 `task_registry.py`，必要时同步更新 DDL 与映射。  
- 权限/运行：检查网络、账号权限；脚本需执行权限（如 `chmod +x run_etl.sh`）。

---

## Cutoff（截止时间）检查

当你需要“上次数据截止到什么时候”“现在应该从哪里开始补跑”时，使用任务 `CHECK_CUTOFF`：

```bash
cd etl_billiards
python -m cli.main --pipeline-flow INGEST_ONLY --tasks CHECK_CUTOFF
```

它会输出：
- `etl_admin.etl_cursor`：每个任务的 `last_start/last_end/last_run_id`（调度游标）
- ODS：对 `DWD_LOAD_FROM_ODS` 依赖的各个 `billiards_ods.*` 表做 `MAX(fetched_at)`（真实已入库 ODS 的截止）
- DWD/DWS：输出若干关键表的最大业务时间/最大更新时刻，便于快速核对

> 如果 `etl_cursor.last_end` 很新，但 ODS 的 `MAX(fetched_at)` 很旧，通常表示在线抓取没跑通（最常见是 `API_TOKEN` 过期导致 401）。

## 冗余抓取方案（推荐）

为避免边界时间丢数（上游延迟写入、接口分页抖动、窗口切换等），建议在 cutoff 基础上向前追加 **1 小时** 冗余量：

- 配置：将 `OVERLAP_SECONDS` 设为 3600（默认 120 秒）

```env
# etl_billiards/.env
OVERLAP_SECONDS=3600
```

冗余方案的关键点是“重抓不重落”，依靠各层的去重/幂等机制只落新数据：
- **ODS 层**：主键/冲突列 UPSERT（重复抓取只会 upsert，不会重复插入）
- **DWD 层**：事实表增量插入 + 主键冲突不重复落（重复范围会被跳过），维度表按 SCD2 合并
- **DWS 层**：对指定日期窗口先 delete 再 upsert（窗口内重算幂等）

> 如果你希望“冗余窗口内的数据发生变更也要覆盖更新”，需要把对应层的冲突策略从 `DO NOTHING` 调整为 `DO UPDATE`（当前实现以“只落新数据”为主）。

## DWS（汇总层）入库

本项目已包含 `billiards_dws` 汇总层（当前提供 `dws_order_summary`）：

1) 初始化 DWS 表结构：

```bash
python -m cli.main --pipeline-flow INGEST_ONLY --tasks INIT_DWS_SCHEMA
```

2) 生成/刷新汇总表（按窗口重算，建议配合 `--window-start/--window-end`）：

```bash
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_BUILD_ORDER_SUMMARY \
  --window-start "2025-10-01 00:00:00" \
  --window-end "2025-12-26 23:59:59"
```

3) 推荐串联（ODS -> DWD -> DWS）：

```bash
# 先跑在线 ODS 抓取（需要有效 API_TOKEN；如果出现 401 请更新 token）
python -m cli.main --pipeline-flow FULL --tasks ODS_MEMBER,ODS_PAYMENT,ODS_REFUND,ODS_SETTLEMENT_RECORDS

# 再把 ODS 增量同步到 DWD
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWD_LOAD_FROM_ODS

# 最后重算 DWS
python -m cli.main --pipeline-flow INGEST_ONLY --tasks DWS_BUILD_ORDER_SUMMARY
```


## 日志 (UTF-8)
- 默认日志目录：`etl_billiards/logs/`
- 每次运行都会生成一个带有时间戳的 `.log` 文件，以便于使用外部工具查看。
常用选项：

- `--log-file` 自定义日志路径（覆盖默认值）。
- `--log-dir` 自定义日志目录。
- `--log-level` 日志级别（`INFO`/`DEBUG`）。
- `--no-log-console` 禁用控制台日志记录（仅写入文件）。

示例（按月切分 + 前后补偿 2h）：
```bash
cd etl_billiards
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
```