# 飞球 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 与映射。