# 飞球 ETL 系统（ODS → DWD）— 详细版

> 本文为项目的详细说明，保持与当前代码一致，覆盖 ODS 任务、DWD 装载、质检及开发扩展要点。

---

## 1. 项目概览

面向门店业务的 ETL：从上游 API 或离线 JSON 采集订单、支付、会员、库存等数据，先落地 **ODS**，再清洗装载 **DWD**（含 SCD2 维度、事实增量），并输出质量校验报表。项目采用模块化/分层架构（配置、API、数据库、Loader/SCD、质量、调度、CLI、测试），统一通过 CLI 调度。

---

## 2. 快速开始（离线示例 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`

**安装依赖**：
```bash
cd etl_billiards
pip install -r requirements.txt
```

**一键 ODS → DWD → 质检（离线回放）**：
```bash
# 初始化 ODS + DWD
python -m etl_billiards.cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA --pipeline-flow INGEST_ONLY

# 灌入示例 JSON 到 ODS（可用 .env 的 INGEST_SOURCE_DIR 覆盖）
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`

---

## 3. 配置与路径
- 示例数据目录：`C:\dev\LLTQ\export\test-json-doc`（可由 `.env` 的 `INGEST_SOURCE_DIR` 覆盖）。  
- 日志/导出目录：`LOG_ROOT`、`EXPORT_ROOT` 见 `.env`。  
- 报表：`etl_billiards/reports/dwd_quality_report.json`。  
- 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）。

**安全提示**：建议将数据库凭证保存在 `.env` 或受控秘钥管理中，生产环境使用最小权限账号。

---

## 4. 目录结构与关键文件
- 根目录：`etl_billiards/` 主代码；`requirements.txt` 依赖；`run_etl.sh/.bat` 启动脚本；`.env/.env.example` 配置；`tmp/` 草稿/调试归档。  
- `config/`：`defaults.py` 默认值，`env_parser.py` 解析 .env，`settings.py` AppConfig 统一加载。  
- `api/`：`client.py` HTTP 请求、重试、分页。  
- `database/`：`connection.py` 连接封装；`operations.py` 批量 upsert；DDL SQL（ODS/DWD）。  
- `tasks/`：  
  - `init_schema_task.py`（INIT_ODS_SCHEMA/INIT_DWD_SCHEMA）；  
  - `manual_ingest_task.py`（示例 JSON → ODS）；  
  - `dwd_load_task.py`（ODS → DWD 映射、SCD2/事实增量）；  
  - 其他任务按需扩展。  
- `loaders/`：ODS/DWD/SCD2 Loader 实现。  
- `scd/`：`scd2_handler.py` 处理维度 SCD2 历史。  
- `quality/`：质量检查器（行数/金额对照）。  
- `orchestration/`：`scheduler.py` 调度；`task_registry.py` 注册；`run_tracker.py` 运行记录；`cursor_manager.py` 水位管理。  
- `scripts/`：重建/测试/探活工具。  
- `docs/`：`ods_to_dwd_mapping.md` 映射说明；`ods_sample_json.md` 示例 JSON 说明；`dwd_quality_check.md` 质检说明。  
- `reports/`：质检输出（如 `dwd_quality_report.json`）。  
- `tests/`：单元/集成测试；`utils/`：通用工具；`backups/`：备份（若存在）。

---

## 5. 架构与流程
执行链路（控制流）：  
1) CLI（`cli/main.py`）解析参数 → 生成 AppConfig → 初始化日志/DB 连接；  
2) 调度层（`scheduler.py`）按 `task_registry.py` 中的注册表实例化任务，设置 run_uuid、cursor（水位）、上下文；  
3) 任务基类模板：  
   - 获取时间窗口/水位（cursor_manager）；  
   - 拉取数据：在线模式调用 `api/client.py` 支持分页、重试；离线模式直接读取 JSON 文件；  
   - 解析与校验：类型转换、必填校验（如任务内部 parse/validate）；  
   - 加载：调用 Loader（`loaders/`）执行批量 Upsert/SCD2/增量写入（底层用 `database/operations.py`）；  
   - 质量检查（如需）：质量模块对行数/金额等进行对比；  
   - 更新水位与运行记录（`run_tracker.py`），提交/回滚事务。

数据流与依赖：  
- 配置：`config/defaults.py` + `.env` + CLI 参数叠加，形成 AppConfig。  
- API 访问：`api/client.py` 支撑分页/重试；离线 ingest 直接读文件。  
- DB 访问：`database/connection.py` 提供连接上下文；`operations.py` 负责批量 upsert/分页写入。  
- ODS：`manual_ingest_task.py` 读取 JSON → ODS 表（保留 payload/来源/时间戳）。  
- DWD：`dwd_load_task.py` 依据 `TABLE_MAP/FACT_MAPPINGS` 从 ODS 选取字段；维度走 SCD2（`scd/scd2_handler.py`），事实走增量；支持字段表达式（JSON->>、CAST）。  
- 质检：`quality` 模块或相关任务对 ODS/DWD 行数、金额等进行比对，输出 `reports/`。  

---

## 6. ODS → DWD 策略
1. ODS 留底：保留源主键、payload、时间/来源信息。  
2. DWD 清洗：维度 SCD2，事实按时间/水位增量；字段类型、单位、枚举标准化，保留可溯源字段。  
3. 业务键统一：site_id、member_id、table_id、order_settle_id、order_trade_no 等统一命名。  
4. 不过度汇总：DWD 只做明细/轻度清洗，汇总留待 DWS/报表。  
5. 去嵌套：数组展开为子表/子行，重复 profile 提炼为维度。  
6. 长期演进：优先加列/加表，避免频繁改已有表结构。

---

## 7. 常用 CLI
```bash
# 运行所有已注册任务
python -m etl_billiards.cli.main
# 运行指定任务
python -m etl_billiards.cli.main --tasks INIT_ODS_SCHEMA,MANUAL_INGEST
# 覆盖 DSN
python -m etl_billiards.cli.main --pg-dsn "postgresql://user:pwd@host:5432/db"
# 覆盖 API
python -m etl_billiards.cli.main --api-base "https://api.example.com" --api-token "..."
# 试运行（不写库）
python -m etl_billiards.cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
```

---

## 8. 测试（ONLINE / OFFLINE）
- `TEST_MODE=ONLINE`：调用真实 API，全链路 E/T/L。  
- `TEST_MODE=OFFLINE`：从 `TEST_JSON_ARCHIVE_DIR` 读取离线 JSON，只做 Transform + Load。  
- `TEST_DB_DSN`：如设置，则集成测试连真库；未设置用内存/临时库。  
示例：
```bash
TEST_MODE=ONLINE pytest tests/unit/test_etl_tasks_online.py
TEST_MODE=OFFLINE TEST_JSON_ARCHIVE_DIR=tests/source-data-doc pytest tests/unit/test_etl_tasks_offline.py
python scripts/test_db_connection.py --dsn postgresql://user:pwd@host:5432/db --query "SELECT 1"
```

---

## 9. 开发与扩展
- 新任务：在 `tasks/` 继承 BaseTask，实现 `get_task_code/execute`，并在 `orchestration/task_registry.py` 注册。  
- 新 Loader/Checker：参考 `loaders/`、`quality/` 复用批量 upsert/质检接口。  
- 配置：`config/defaults.py` + `.env` + CLI 叠加，新增配置需在 defaults 与 env_parser 中声明。

---

## 10. ODS 任务上线指引
- 任务注册脚本：`etl_billiards/database/seed_ods_tasks.sql`（替换 store_id 后执行：`psql "$PG_DSN" -f ...`）。  
- 确认 `etl_admin.etl_task` 中已启用所需 ODS 任务。  
- 离线回放：可用 `scripts/rebuild_ods_from_json`（如有）从本地 JSON 重建 ODS。  
- 单测：`pytest etl_billiards/tests/unit/test_ods_tasks.py`。

---

## 11. ODS 表概览（数据路径）

| ODS 表名                             | 接口 Path                                         | 数据列表路径                  |
| ------------------------------------ | ------------------------------------------------- | ----------------------------- |
| assistant_accounts_master            | /PersonnelManagement/SearchAssistantInfo          | data.assistantInfos           |
| assistant_service_records            | /AssistantPerformance/GetOrderAssistantDetails    | data.orderAssistantDetails    |
| assistant_cancellation_records       | /AssistantPerformance/GetAbolitionAssistant       | data.abolitionAssistants      |
| goods_stock_movements                | /GoodsStockManage/QueryGoodsOutboundReceipt       | data.queryDeliveryRecordsList |
| goods_stock_summary                  | /TenantGoods/GetGoodsStockReport                  | data                          |
| group_buy_packages                   | /PackageCoupon/QueryPackageCouponList             | data.packageCouponList        |
| group_buy_redemption_records         | /Site/GetSiteTableUseDetails                      | data.siteTableUseDetailsList  |
| member_profiles                      | /MemberProfile/GetTenantMemberList                | data.tenantMemberInfos        |
| member_balance_changes               | /MemberProfile/GetMemberCardBalanceChange         | data.tenantMemberCardLogs     |
| member_stored_value_cards            | /MemberProfile/GetTenantMemberCardList            | data.tenantMemberCards        |
| payment_transactions                 | /PayLog/GetPayLogListPage                         | data                          |
| platform_coupon_redemption_records   | /Promotion/GetOfflineCouponConsumePageList        | data                          |
| recharge_settlements                 | /Site/GetRechargeSettleList                       | data.settleList               |
| refund_transactions                  | /Order/GetRefundPayLogList                        | data                          |
| settlement_records                   | /Site/GetAllOrderSettleList                       | data.settleList               |
| settlement_ticket_details            | /Order/GetOrderSettleTicketNew                    | 完整 JSON                     |
| site_tables_master                   | /Table/GetSiteTables                              | data.siteTables               |
| stock_goods_category_tree            | /TenantGoodsCategory/QueryPrimarySecondaryCategory| data.goodsCategoryList        |
| store_goods_master                   | /TenantGoods/GetGoodsInventoryList                | data.orderGoodsList           |
| store_goods_sales_records            | /TenantGoods/GetGoodsSalesList                    | data.orderGoodsLedgers        |
| table_fee_discount_records           | /Site/GetTaiFeeAdjustList                         | data.taiFeeAdjustInfos        |
| table_fee_transactions               | /Site/GetSiteTableOrderDetails                    | data.siteTableUseDetailsList  |
| tenant_goods_master                  | /TenantGoods/QueryTenantGoods                     | data.tenantGoodsList          |

> 完整字段级映射见 `docs/` 与 ODS/DWD DDL。

---

## 12. DWD 维度与建模要点
1. 颗粒一致、单一业务键：一张 DWD 表只承载一种业务事件/颗粒，避免混颗粒。  
2. 先理解业务链路，再建模；不要机械按 JSON 列表建表。  
3. 业务键统一：site_id、member_id、table_id、order_settle_id、order_trade_no 等必须一致命名。  
4. 保留明细，不过度汇总；聚合留到 DWS/报表。  
5. 清洗标准化同时保留溯源字段（源主键、时间、金额、payload）。  
6. 去嵌套与解耦：数组展开子行，重复 profile 提炼维度。  
7. 演进优先加列/加表，减少对已有表结构的破坏。

---

## 13. 当前状态（2025-12-09）
- 示例 JSON 已全量灌入，DWD 行数与 ODS 对齐。  
- 分类维度已展平大类+子类：`dim_goods_category` 26 行（category_level/leaf 已赋值）。  
- 部分空字段源数据即为空，如需补值请先确认上游。

---

## 14. 可精简/归档
- `tmp/`、`tmp/etl_billiards_misc/` 中草稿、旧备份、调试脚本仅供参考，不影响运行。  
- 根级保留必要文件（README、requirements、run_etl.*、.env/.env.example），其他临时文件已移至 tmp。

---

## 15. FAQ
- 字段空值：若映射已存在且源列非空仍为空，再检查上游 JSON；维度 SCD2 按全量合并。  
- DSN/路径：确认 `.env` 中 `PG_DSN`、`INGEST_SOURCE_DIR` 与本地一致。  
- 新增任务：在 `tasks/` 实现并注册到 `task_registry.py`，必要时同步更新 DDL 与映射。  
- 权限/运行：检查网络、账号权限；脚本需执行权限（如 `chmod +x run_etl.sh`）。