4.0 KiB
4.0 KiB
飞球 ETL 系统（ODS→DWD 全流程说明）
本项目实现门店业务的 ETL 流水线：拉取/或离线灌入上游 JSON，落地 ODS，清洗装载 DWD（含 SCD2 维度、事实增量），并提供质量校验报表。
快速运行（本地离线示例 JSON）
- 依赖与环境
- 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。
- 安装
cd etl_billiards pip install -r requirements.txt - 一键离线回放（ODS→DWD→质检）
# 初始化 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 - 单独跑某类任务
- 仅建表：
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 与映射。