89 lines
4.6 KiB
Markdown
89 lines
4.6 KiB
Markdown
# 飞球 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) 安装依赖：
|
||
```bash
|
||
cd etl_billiards
|
||
pip install -r requirements.txt
|
||
# 开发模式：pip install -e .
|
||
```
|
||
3) 配置 .env（示例关键项）：
|
||
```bash
|
||
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) 初始化库表：
|
||
```bash
|
||
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) 运行任务（示例）：
|
||
```bash
|
||
# 默认任务列表（见 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。
|
||
|