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 维度、事实增量），并提供质量校验报表。
## 功能要点 ## 快速运行（本地离线示例 JSON）
- 双层形态：ODS 原始保留 + DWD 清洗标准化，支持回放与重载。 1) 依赖与环境
- 任务调度：ETLScheduler 统一管理任务、日志、失败隔离，CLI 友好。 - Python 3.10+；PostgreSQL 可用。
- 配置体系：默认值 + .env + CLI 覆盖，便于多环境运行。 - 关键配置：`.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`。
- 批量入库：通用 ODS Loader / SCD2 维度合并 / 事实增量写入。 2) 安装
- 回归校验：示例 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) 安装依赖：
```bash ```bash
cd etl_billiards cd etl_billiards
pip install -r requirements.txt pip install -r requirements.txt
# 开发模式：pip install -e .
``` ```
3) 配置 .env（示例关键项）： 3) 一键离线回放（ODS→DWD→质检）
```bash ```bash
PG_DSN=postgresql://user:pwd@host:5432/LLZQ-test # 初始化 ODS+DWD
API_BASE=https://api.example.com python -m etl_billiards.cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA --pipeline-flow INGEST_ONLY
API_TOKEN=your_token # 灌入示例 JSON 到 ODS
STORE_ID=2790685415443269 python -m etl_billiards.cli.main --tasks MANUAL_INGEST --pipeline-flow INGEST_ONLY --ingest-source "C:\dev\LLTQ\export\test-json-doc"
EXPORT_ROOT=C:\dev\LLTQ\export\JSON # 从 ODS 装载 DWD
LOG_ROOT=C:\dev\LLTQ\export\LOG python -m etl_billiards.cli.main --tasks DWD_LOAD_FROM_ODS --pipeline-flow INGEST_ONLY
INGEST_SOURCE_DIR=C:\dev\LLTQ\export\test-json-doc # 质检报表
``` python -m etl_billiards.cli.main --tasks DWD_QUALITY_CHECK --pipeline-flow INGEST_ONLY
4) 初始化库表： # 报表输出：etl_billiards/reports/dwd_quality_report.json
```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"
``` ```
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/日志上下文 -> 实例化任务 -> 拉取/清洗/写入。 - 示例数据目录：`C:\dev\LLTQ\export\test-json-doc`（可通过 `.env` 的 `INGEST_SOURCE_DIR` 覆盖）。
- ODS 任务：调用 API，分页提取，字段解析后批量 upsert；payload 保留原始 JSON。 - 日志/导出目录：`LOG_ROOT`、`EXPORT_ROOT` 见 `.env`。
- DWD 任务：维度表做 SCD2，事实表按时间水位增量写入。 - 质量报表：`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。 - config：默认值、环境变量解析（AppConfig）。
- 离线模式：TEST_MODE=OFFLINE TEST_JSON_ARCHIVE_DIR=... pytest tests/unit/test_etl_tasks_offline.py。 - api：HTTP 客户端封装。
- 数据库连通：python scripts/test_db_connection.py --dsn <PG_DSN> --query "SELECT 1"。 - 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）
- .env.example 罗列全部配置；config/defaults.py 给出默认值与任务窗口。 - ODS & DWD 已全量跑通，示例 JSON 全部灌入；DWD 维度/事实行数与 ODS 匹配。
- loaders/ods/generic.py 支持自定义主键/冲突列； asks/manual_ingest_task.py 可将示例 JSON 快速灌入对应 ODS 表。 - 分类维度已展平大类+子类：`dim_goods_category` 行数 26（大类 pid=0，子类 pid 指向大类，category_level 已赋值）。
- 添加新任务：在 asks/ 中实现并在 orchestration/task_registry.py 注册。 - 全空字段多因源数据为空；若需补充请先确认上游是否提供。
## ODS 任务与调度使用 ## 过期/可精简内容
- 注册：etl_admin.etl_task 已启用 INIT_ODS_SCHEMA、MANUAL_INGEST（store_id=2790685415443269，可按需追加其他任务）。 - `etl_billiards/tmp & Delete/`、`tmp/` 下的草稿 SQL/文档（如 `schema_v2.sql`、`DWD层设计草稿.md`、`schema_dwd.sql`）仅供对照，不参与任务；可按需归档或删除以缩减体积。
- 示例数据目录：默认 C:\dev\LLTQ\export\test-json-doc（可在 .env 的 INGEST_SOURCE_DIR 覆盖）。 - `etl_billiards/backups/` 保留当前可用版本（近期生成的备份可保留，旧备份可清理）。
- 一键重建+灌入： - 顶层零散脚本（如 `tmp_*.py`）为一次性调试，可在确认无用后删除。
`bash - 若不再使用 run_etl.bat/run_etl.sh，可改用统一 CLI 命令或 run_ods.bat（若存在）。
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。
## 常见问题
- 字段空值：若映射已存在且源列非空仍为空，可检查上游 JSON 是否缺值；维度 SCD2 会按全量合并。
- DSN/目录缺失：确认 `.env` 中 PG_DSN、INGEST_SOURCE_DIR 与本地目录一致。
- 新增任务：在 `tasks/` 实现并注册到 `task_registry.py`，必要时补充 DDL 与映射。

281
README_FULL.md Normal file
View File

@@ -0,0 +1,281 @@
# 飞球 ETL 系统（ODS → DWD）合并版
> 本文在不改变现有用法的前提下，整合了两份历史说明的有效信息；所有冲突以当前仓库中的 `README.md` 为准，补充了架构、测试、迁移、ODS 任务指引、表映射与 DWD 建模原则等内容。
---
## 1. 项目概述
面向门店业务的数据工程项目：从上游业务 API 或本地离线 JSON 拉取原始数据，先落地 **ODS**，再清洗装载 **DWD**（含 SCD2 维度历史与事实增量），并提供数据质量校验报表。项目采用模块化、分层架构（配置、API、数据库、加载器/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`。
- 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）。
**安全提示：** 建议将数据库口令仅保存在 `.env` 或密钥管理平台，避免在示例或脚本中硬编码；生产环境请使用具有最小权限的数据库账号。
---
## 4. 目录结构与主要文件（精要）
- 根目录：`etl_billiards/` 主代码；`requirements.txt` 依赖；`run_etl.sh/.bat` 启动脚本；`.env/.env.example` 配置；`tmp/` 放置草稿/备份。
- `config/`：`defaults.py` 默认值，`env_parser.py` 解析 `.env`，`settings.py` 统一配置加载。
- `api/`：`client.py` HTTP 请求、重试与分页。
- `database/`：`connection.py` 连接封装，`operations.py` 批量 upsert，DDL SQL。
- `tasks/`：业务任务（见第 9 章与第 10 章）。
- `loaders/`：ODS/DWD/SCD2 Loader 实现。
- `scd/`：`scd2_handler.py` 处理维度 SCD2 历史。
- `quality/`：质量检查器（行数/金额对照等）。
- `orchestration/`：`scheduler.py` 调度；`task_registry.py` 注册；`run_tracker.py` 运行记录；`cursor_manager.py` 增量游标。
- `docs/`：映射与示例文档。
- `reports/`：质检输出（如 `dwd_quality_report.json`）。
- `tests/`：单元/集成测试；`utils/`：通用工具。
---
## 5. 架构与流程
```
CLI (etl_billiards/cli/main.py)
↓
Orchestration (scheduler / task_registry / run_tracker / cursor_manager)
↓
Tasks (orders/payments/members/…)
↙ ↓ ↘
Loaders SCD2 Quality
↓
Models
↓
API
↓
Database
↓
Config
```
**执行模板（任务层）：** 统一模板方法包含：读取增量窗口 → 拉取数据（支持分页/重试）→ 解析与校验 → Loader 写库（Upsert/SCD2）→ 质量检查 → 更新游标与运行记录。
---
## 6. ODS → DWD 双阶段策略
为支持回溯/重放与稳定建模，项目采用双阶段：
1. **ODS 落地**：将原始记录（含分页/抓取时间/来源）按表落地到 `billiards_ods.*`，保留源主键与 payload 以保证可追溯。
2. **DWD 清洗**：从 ODS 读取 payload，进行解析、标准化与 SCD2 处理，写入 `billiards.*` 的维度/事实表；事实表走时间/水位增量。
---
## 7. 常用命令（CLI）
```bash
# 运行全部已注册任务（按 task_registry）
python -m etl_billiards.cli.main
# 仅运行指定任务
python -m etl_billiards.cli.main --tasks ORDERS,PAYMENTS,MEMBERS
# 覆盖数据库 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 ORDERS
```
> 实际启用的任务代码与管道以当前 `task_registry.py` 与数据库任务配置为准。
---
## 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
# 离线模式回放归档 JSON
TEST_MODE=OFFLINE TEST_JSON_ARCHIVE_DIR=tests/source-data-doc pytest tests/unit/test_etl_tasks_offline.py
# 脚本化组合
python scripts/run_tests.py --suite offline --mode OFFLINE --db-dsn postgresql://user:pwd@localhost:5432/testdb
python scripts/run_tests.py --preset offline_realdb
```
**数据库连通性检查：**
```bash
python scripts/test_db_connection.py --dsn postgresql://user:pwd@host:5432/db --query "SELECT 1"
```
---
## 9. 开发与扩展指南
**添加新任务：**
```python
from tasks.base_task import BaseTask
class MyTask(BaseTask):
def get_task_code(self) -> str:
return "MY_TASK"
def execute(self) -> dict:
window_start, window_end, _ = self._get_time_window()
records, _ = self.api.get_paginated(...)
parsed = [self._parse(r) for r in records]
loader = MyLoader(self.db)
inserted, updated, _ = loader.upsert(parsed)
self.db.commit()
return self._build_result("SUCCESS", {"inserted": inserted, "updated": updated})
```
在 `orchestration/task_registry.py` 注册：
```python
from tasks.my_task import MyTask
default_registry.register("MY_TASK", MyTask)
```
**添加新 Loader / Checker：** 参见 `loaders/`、`quality/` 模块，优先复用批量 upsert 与返回写入统计的统一接口。
---
## 10. ODS 任务上线指引（摘要）
- 任务注册脚本：`etl_billiards/database/seed_ods_tasks.sql`，将其中 `store_id` 替换为实际值后执行：
```bash
psql "$PG_DSN" -f etl_billiards/database/seed_ods_tasks.sql
```
- 调度：确认 `etl_admin.etl_task` 中已启用所需 ODS 任务（任务代码见 seed 脚本）。
- 离线回灌：开发环境可用 `rebuild_ods_from_json` 初始化 ODS（生产慎用）。
- 测试：`pytest etl_billiards/tests/unit/test_ods_tasks.py` 覆盖核心 ODS 任务。
---
## 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. **保留明细，不做过度汇总**：DWD 仅存明细，聚合到 DWS 完成。
5. **统一清洗且可追溯**：类型/单位/枚举标准化，并保留源主键与原始字段确保可追溯。
6. **扁平化、去嵌套**：数组拆子表，重复 profile 抽维度，去除分页壳。
7. **长期稳定、可扩展**：优先加字段/增表/在 DWS 派生，避免频繁重构 DWD 表。
---
## 13. 当前状态（2025-12-09）
- 示例 JSON 已全量灌入；DWD 行数与 ODS 对齐。
- 分类维度已展平大类+子类：`dim_goods_category` 26 行（`category_level/leaf` 已赋值）。
- 部分空值来自上游源数据为空；补值需先确认上游是否提供。
---
## 14. 可精简/归档
- `tmp/`、`tmp/etl_billiards_misc/`、`etl_billiards/tmp & Delete/` 下草稿/旧备份/一次性脚本不参与运行，可按需归档或清理。
- 顶层仅保留必要文件（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`）。
---
> 以上为合并后的单点说明文档。若需拆分为「快速开始 / 架构设计 / 迁移指南 / 开发扩展」等多份文档，可按章节直接拆分。