67 lines
4.0 KiB
Markdown
67 lines
4.0 KiB
Markdown
# 飞球 ETL 系统（ODS→DWD 全流程说明）
|
||
|
||
本项目实现门店业务的 ETL 流水线：拉取/或离线灌入上游 JSON，落地 ODS，清洗装载 DWD（含 SCD2 维度、事实增量），并提供质量校验报表。
|
||
|
||
## 快速运行（本地离线示例 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
|
||
```
|
||
3) 一键离线回放（ODS→DWD→质检）
|
||
```bash
|
||
# 初始化 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`
|
||
|
||
## 数据与目录约定
|
||
- 示例数据目录：`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。
|
||
|
||
## 模块与主要文件
|
||
- 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/任务文件的备份版本。
|
||
|
||
## 当前进展（2025-12-09）
|
||
- ODS & DWD 已全量跑通，示例 JSON 全部灌入；DWD 维度/事实行数与 ODS 匹配。
|
||
- 分类维度已展平大类+子类：`dim_goods_category` 行数 26（大类 pid=0，子类 pid 指向大类，category_level 已赋值）。
|
||
- 全空字段多因源数据为空；若需补充请先确认上游是否提供。
|
||
|
||
## 过期/可精简内容
|
||
- `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 与映射。
|