飞球 ETL 系统

面向门店业务的 ETL 流水线：从上游 API 拉取订单/支付/会员/库存等 JSON，先落地 ODS，随后清洗装载 DWD（含 SCD2 维度、事实增量），并提供质量校验与回归验证工具。

功能要点

• 双层形态：ODS 原始保留 + DWD 清洗标准化，支持回放与重载。
• 任务调度：ETLScheduler 统一管理任务、日志、失败隔离，CLI 友好。
• 配置体系：默认值 + .env + CLI 覆盖，便于多环境运行。
• 批量入库：通用 ODS Loader / SCD2 维度合并 / 事实增量写入。
• 回归校验：示例 JSON、行数对照、质量报告，便于快速验证。

仓库结构

• etl_billiards/config：默认配置、环境变量解析、CLI 覆盖。
• etl_billiards/api：HTTP 客户端与重试、分页封装。
• etl_billiards/database：连接管理、批量 upsert 封装、DDL。
• etl_billiards/tasks：业务任务（ODS/DWD/初始化/手工灌入等）。
• etl_billiards/loaders：ODS/DWD/SCD Loader 实现。
• etl_billiards/orchestration：调度器与任务注册。
• etl_billiards/scripts：测试、重建、探活脚本。
• etl_billiards/reports：质量报告输出。
• etl_billiards/docs：ODS->DWD 映射说明、样例 JSON 说明。

支持的主要任务

• ODS：订单结算、台费流水、助教流水/废除、库存、支付、退款、会员、充值结算等。
• DWD：维度表（门店/台桌/会员/助教/商品等）与事实表（结算、支付、退款、充值、台费、商品销售等）。
• 初始化与手工灌入：INIT_ODS_SCHEMA、MANUAL_INGEST。

快速开始

1. 环境：Python 3.10+，PostgreSQL 可用；在 etl_billiards/ 下运行命令。
2. 安装依赖：

   cd etl_billiards
   pip install -r requirements.txt
   # 开发模式：pip install -e .
   

3. 配置 .env（示例关键项）：

   PG_DSN=postgresql://user:pwd@host:5432/LLZQ-test
   API_BASE=https://api.example.com
   API_TOKEN=your_token
   STORE_ID=2790685415443269
   EXPORT_ROOT=C:\dev\LLTQ\export\JSON
   LOG_ROOT=C:\dev\LLTQ\export\LOG
   INGEST_SOURCE_DIR=C:\dev\LLTQ\export\test-json-doc
   

4. 初始化库表：

   python -m cli.main --tasks INIT_ODS_SCHEMA --pipeline-flow INGEST_ONLY --ingest-source "C:\dev\LLTQ\export\test-json-doc"
   # 或直接用 psql 执行 schema_*.sql
   

5. 运行任务（示例）：

   # 默认任务列表（见 config/defaults.py）
   python -m cli.main
   # 指定任务
   python -m cli.main --tasks settlement_records,recharge_settlements
   # 仅手工灌入示例 JSON
   python -m cli.main --tasks MANUAL_INGEST --pipeline-flow INGEST_ONLY --ingest-source "C:\dev\LLTQ\export\test-json-doc"
   

运行与数据流

• CLI 解析参数 -> AppConfig.load 合并配置 -> ETLScheduler 创建 DB/API/日志上下文 -> 实例化任务 -> 拉取/清洗/写入。
• ODS 任务：调用 API，分页提取，字段解析后批量 upsert；payload 保留原始 JSON。
• DWD 任务：维度表做 SCD2，事实表按时间水位增量写入。

测试与回归

• 单测/集成：pytest 或 python scripts/run_tests.py --suite online。
• 离线模式：TEST_MODE=OFFLINE TEST_JSON_ARCHIVE_DIR=... pytest tests/unit/test_etl_tasks_offline.py。
• 数据库连通：python scripts/test_db_connection.py --dsn <PG_DSN> --query "SELECT 1"。

其他提示

• .env.example 罗列全部配置；config/defaults.py 给出默认值与任务窗口。
• loaders/ods/generic.py 支持自定义主键/冲突列； asks/manual_ingest_task.py 可将示例 JSON 快速灌入对应 ODS 表。
• 添加新任务：在 asks/ 中实现并在 orchestration/task_registry.py 注册。

ODS 任务与调度使用

• 注册：etl_admin.etl_task 已启用 INIT_ODS_SCHEMA、MANUAL_INGEST（store_id=2790685415443269，可按需追加其他任务）。
• 示例数据目录：默认 C:\dev\LLTQ\export\test-json-doc（可在 .env 的 INGEST_SOURCE_DIR 覆盖）。
• 一键重建+灌入： bash python -m cli.main --tasks INIT_ODS_SCHEMA,MANUAL_INGEST --pipeline-flow INGEST_ONLY --ingest-source "C:\dev\LLTQ\export\test-json-doc"
• 行数对照：etl_billiards/ods_row_report.json 存示例 JSON 行数与 ODS 行数，可用于回归校验。
• 备份：etl_billiards/backups/ 保存当前 schema_ODS_doc.sql、 asks/manual_ingest_task.py 版本。
• 充值结算 ODS：recharge_settlements 已按 settleList 扁平化主字段（ echarge_order_id 主键，金额/状态/快照等列），site_profile 与 payload 保留原始 JSON；任务 recharge_settlements 直接写入该表，手工灌入会自动展开 echarge_settlements.json。