root/feiqiu-ETL
Template
1
0
Fork 0
Code Pull Requests Packages Releases Wiki Activity

整理项目

Browse Source
This commit is contained in:
Neo
2025-12-09 05:42:57 +08:00
parent 561c640700
commit 0c29bd41f8
2 changed files with 334 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

128
README.md
View File

@@ -1,88 +1,66 @@
# 飞球 ETL 系统
# 飞球 ETL 系统（ODS→DWD 全流程说明）
面向门店业务的 ETL 流水线：从上游 API 拉取订单/支付/会员/库存等 JSON，先落地 ODS，随后清洗装载 DWD（含 SCD2 维度、事实增量），并提供质量校验与回归验证工具。
本项目实现门店业务的 ETL 流水线：拉取/或离线灌入上游 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) 安装依赖：
## 快速运行（本地离线示例 JSON）
1) 依赖与环境
- Python 3.10+；PostgreSQL 可用。
- 关键配置：`.env` 中 `PG_DSN=postgresql://local-Python:Neo-local-1991125@100.64.0.4:5432/LLZQ-test`，`INGEST_SOURCE_DIR=C:\dev\LLTQ\export\test-json-doc`。
2) 安装
```bash
cd etl_billiards
pip install -r requirements.txt
# 开发模式：pip install -e .
```
3) 配置 .env（示例关键项）：
3) 一键离线回放（ODS→DWD→质检）
```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"
# 初始化 ODS+DWD
python -m etl_billiards.cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA --pipeline-flow INGEST_ONLY
# 灌入示例 JSON 到 ODS
python -m etl_billiards.cli.main --tasks MANUAL_INGEST --pipeline-flow INGEST_ONLY --ingest-source "C:\dev\LLTQ\export\test-json-doc"
# 从 ODS 装载 DWD
python -m etl_billiards.cli.main --tasks DWD_LOAD_FROM_ODS --pipeline-flow INGEST_ONLY
# 质检报表
python -m etl_billiards.cli.main --tasks DWD_QUALITY_CHECK --pipeline-flow INGEST_ONLY
# 报表输出：etl_billiards/reports/dwd_quality_report.json
```
4) 单独跑某类任务
- 仅建表：`python -m etl_billiards.cli.main --tasks INIT_ODS_SCHEMA`
- 仅 ODS 灌入：`python -m etl_billiards.cli.main --tasks MANUAL_INGEST`
- 仅 DWD 装载：`python -m etl_billiards.cli.main --tasks INIT_DWD_SCHEMA,DWD_LOAD_FROM_ODS`
## 运行与数据流
- CLI 解析参数 -> AppConfig.load 合并配置 -> ETLScheduler 创建 DB/API/日志上下文 -> 实例化任务 -> 拉取/清洗/写入。
- ODS 任务：调用 API，分页提取，字段解析后批量 upsert；payload 保留原始 JSON。
- DWD 任务：维度表做 SCD2，事实表按时间水位增量写入。
## 数据与目录约定
- 示例数据目录：`C:\dev\LLTQ\export\test-json-doc`（可通过 `.env` 的 `INGEST_SOURCE_DIR` 覆盖）。
- 日志/导出目录：`LOG_ROOT`、`EXPORT_ROOT` 见 `.env`。
- 质量报表：`etl_billiards/reports/dwd_quality_report.json`。
- ODS/DWD DDL：`etl_billiards/database/schema_ODS_doc.sql`、`etl_billiards/database/schema_dwd_doc.sql`。
- 任务注册：`etl_billiards/orchestration/task_registry.py`，默认启用 INIT_ODS_SCHEMA、MANUAL_INGEST、INIT_DWD_SCHEMA、DWD_LOAD_FROM_ODS、DWD_QUALITY_CHECK。
## 测试与回归
- 单测/集成：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"。
## 模块与主要文件
- config：默认值、环境变量解析（AppConfig）。
- api：HTTP 客户端封装。
- database：连接管理、批量 upsert、DDL SQL。
- tasks：业务任务（ODS、DWD、初始化、手工灌入、质检）。
- loaders：ODS/DWD/SCD2 Loader。
- scd：SCD2 历史版本处理。
- quality：质量检查器（行数/金额对照等）。
- orchestration：调度、任务注册、运行追踪。
- scripts：测试、重建、探活等脚本。
- docs：ODS→DWD 映射说明（`docs/ods_to_dwd_mapping.md`）、样例 JSON 说明。
- reports：质检结果输出目录。
- backups：关键 SQL/任务文件的备份版本。
## 其他提示
- .env.example 罗列全部配置；config/defaults.py 给出默认值与任务窗口。
- loaders/ods/generic.py 支持自定义主键/冲突列； asks/manual_ingest_task.py 可将示例 JSON 快速灌入对应 ODS 表。
- 添加新任务：在 asks/ 中实现并在 orchestration/task_registry.py 注册。
## 当前进展（2025-12-09）
- ODS & DWD 已全量跑通，示例 JSON 全部灌入；DWD 维度/事实行数与 ODS 匹配。
- 分类维度已展平大类+子类：`dim_goods_category` 行数 26（大类 pid=0，子类 pid 指向大类，category_level 已赋值）。
- 全空字段多因源数据为空；若需补充请先确认上游是否提供。
## 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。
## 过期/可精简内容
- `etl_billiards/tmp & Delete/`、`tmp/` 下的草稿 SQL/文档（如 `schema_v2.sql`、`DWD层设计草稿.md`、`schema_dwd.sql`）仅供对照，不参与任务；可按需归档或删除以缩减体积。
- `etl_billiards/backups/` 保留当前可用版本（近期生成的备份可保留，旧备份可清理）。
- 顶层零散脚本（如 `tmp_*.py`）为一次性调试，可在确认无用后删除。
- 若不再使用 run_etl.bat/run_etl.sh，可改用统一 CLI 命令或 run_ods.bat（若存在）。
## 常见问题
- 字段空值：若映射已存在且源列非空仍为空，可检查上游 JSON 是否缺值；维度 SCD2 会按全量合并。
- DSN/目录缺失：确认 `.env` 中 PG_DSN、INGEST_SOURCE_DIR 与本地目录一致。
- 新增任务：在 `tasks/` 实现并注册到 `task_registry.py`，必要时补充 DDL 与映射。