ODS 完成

2025-11-30 07:19:05 +08:00
parent b9b050bb5d
commit a6ad343092
81 changed files with 15695 additions and 227180 deletions
--- a/etl_billiards/README.md
+++ b/etl_billiards/README.md
@@ -71,7 +71,7 @@ cp .env.example .env

 ```bash
 # 数据库
-PG_DSN=postgresql://user:password@localhost:5432/LLZQ
+PG_DSN=postgresql://user:password@localhost:5432/....

 # API
 API_BASE=https://api.example.com
@@ -114,13 +114,13 @@ run_etl.bat --tasks ORDERS
 - 日志目录：使用 `LOG_ROOT` 指定，例如

  ```bash
-  ls -la D:\LLZQ\DB\logs/
+  ls -la C:\dev\LLTQ\export\LOG/
  ```

 - 导出目录：使用 `EXPORT_ROOT` 指定，例如

  ```bash
-  ls -la D:\LLZQ\DB\export/
+  ls -la C:\dev\LLTQ\export\JSON/
  ```

 ---
@@ -152,10 +152,10 @@ python -m cli.main --dry-run --tasks ORDERS

 ```json
 {
-    "python.linting.enabled": true,
-    "python.linting.pylintEnabled": true,
-    "python.formatting.provider": "black",
-    "python.testing.pytestEnabled": true
+  "python.linting.enabled": true,
+  "python.linting.pylintEnabled": true,
+  "python.formatting.provider": "black",
+  "python.testing.pytestEnabled": true
 }
 ```

@@ -195,7 +195,7 @@ pytest --cov=. --cov-report=html

 - `TEST_MODE=ONLINE`（默认）时，测试会模拟实时 API，完整执行 E/T/L。
 - `TEST_MODE=OFFLINE` 时，测试改为从 `TEST_JSON_ARCHIVE_DIR` 指定的归档 JSON 中读取数据，仅做 Transform + Load，适合验证本地归档数据是否仍可回放。
- `TEST_JSON_ARCHIVE_DIR`：离线 JSON 归档目录（示例：`tests/testdata_json` 或 CI 产出的快照）。
+- `TEST_JSON_ARCHIVE_DIR`：离线 JSON 归档目录（示例：`tests/source-data-doc` 或 CI 产出的快照）。
 - `TEST_JSON_TEMP_DIR`：测试生成的临时 JSON 输出目录，便于隔离每次运行的数据。
 - `TEST_DB_DSN`：可选，若设置则单元测试会连接到此 PostgreSQL DSN，实打实执行写库；留空时测试使用内存伪库，避免依赖数据库。

@@ -206,7 +206,7 @@ pytest --cov=. --cov-report=html
 TEST_MODE=ONLINE pytest tests/unit/test_etl_tasks_online.py

 # 离线模式使用归档 JSON 覆盖所有任务
-TEST_MODE=OFFLINE TEST_JSON_ARCHIVE_DIR=tests/testdata_json pytest tests/unit/test_etl_tasks_offline.py
+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 online --mode ONLINE --keyword ORDERS
@@ -227,19 +227,19 @@ python scripts/run_tests.py --list-presets   # 查看或自定义 scripts/test_p

 `test_presets.py` 充当“指令仓库”。每个预置都是一个字典，常用字段解释如下：

-| 字段 | 作用 |
-| ---- | ---- |
-| `suite` | 复用 `run_tests.py` 内置套件（online/offline/integration，可多选） |
-| `tests` | 追加任意 pytest 路径，例如 `tests/unit/test_config.py` |
-| `mode` | 覆盖 `TEST_MODE`（ONLINE / OFFLINE） |
-| `db_dsn` | 覆盖 `TEST_DB_DSN`，用于连入真实测试库 |
-| `json_archive` / `json_temp` | 配置离线 JSON 归档与临时目录 |
-| `keyword` | 映射到 `pytest -k`，用于关键字过滤 |
-| `pytest_args` | 附加 pytest 参数，例 `-vv --maxfail=1` |
-| `env` | 额外环境变量列表，如 `["STORE_ID=123"]` |
-| `preset_meta` | 说明性文字，便于描述场景 |
+| 字段                         | 作用                                                               |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `suite`                      | 复用 `run_tests.py` 内置套件（online/offline/integration，可多选） |
+| `tests`                      | 追加任意 pytest 路径，例如 `tests/unit/test_config.py`             |
+| `mode`                       | 覆盖 `TEST_MODE`（ONLINE / OFFLINE）                               |
+| `db_dsn`                     | 覆盖 `TEST_DB_DSN`，用于连入真实测试库                             |
+| `json_archive` / `json_temp` | 配置离线 JSON 归档与临时目录                                       |
+| `keyword`                    | 映射到 `pytest -k`，用于关键字过滤                                 |
+| `pytest_args`                | 附加 pytest 参数，例 `-vv --maxfail=1`                             |
+| `env`                        | 额外环境变量列表，如 `["STORE_ID=123"]`                            |
+| `preset_meta`                | 说明性文字，便于描述场景                                           |

-示例：`offline_realdb` 预置会设置 `TEST_MODE=OFFLINE`、指定 `tests/testdata_json` 为归档目录，并通过 `db_dsn` 连到测试库。执行 `python scripts/run_tests.py --preset offline_realdb` 或 `python scripts/test_presets.py --preset offline_realdb` 即可复用该组合，保证本地、CI 与生产回放脚本一致。
+示例：`offline_realdb` 预置会设置 `TEST_MODE=OFFLINE`、指定 `tests/source-data-doc` 为归档目录，并通过 `db_dsn` 连到测试库。执行 `python scripts/run_tests.py --preset offline_realdb` 或 `python scripts/test_presets.py --preset offline_realdb` 即可复用该组合，保证本地、CI 与生产回放脚本一致。

 #### 3.3.3 数据库连通性快速检查

@@ -250,7 +250,7 @@ python scripts/run_tests.py --list-presets   # 查看或自定义 scripts/test_p
 python scripts/test_db_connection.py

 # 临时指定 DSN，并检查任务配置表
-python scripts/test_db_connection.py --dsn postgresql://user:pwd@host:5432/LLZQ-test --query "SELECT count(*) FROM etl_admin.etl_task"
+python scripts/test_db_connection.py --dsn postgresql://user:pwd@host:5432/.... --query "SELECT count(*) FROM etl_admin.etl_task"
 ```

 脚本返回 0 代表连接与查询成功；若返回非 0，可结合第 8 章“常见问题排查”的数据库章节（网络、防火墙、账号权限等）先定位问题，再运行完整 ETL。
@@ -342,7 +342,7 @@ etl_billiards/
 │   │   ├── test_config.py
 │   │   └── test_parsers.py
 │   ├── testdata_json/           # 清洗入库用的测试Json文件
-│   │   └── XX.json              
+│   │   └── XX.json
 │   └── integration/             # 集成测试
 │       ├── __init__.py
 │       └── test_database.py
@@ -353,29 +353,29 @@ etl_billiards/

 ### 4.2 各模块职责概览

- **config/**  
+- **config/**
  - 统一配置入口，支持默认值、环境变量、命令行参数三层覆盖。
- **database/**  
+- **database/**
  - 封装 PostgreSQL 连接与批量操作（插入、更新、Upsert 等）。
- **api/**  
+- **api/**
  - 对上游业务 API 的 HTTP 调用进行统一封装，支持重试、分页与超时控制。
- **models/**  
+- **models/**
  - 提供类型解析器（时间戳、金额、整数等）与业务级数据校验器。
- **loaders/**  
+- **loaders/**
  - 提供事实表与维度表的加载逻辑（包含批量 Upsert、统计写入结果等）。
- **scd/**  
+- **scd/**
  - 维度型数据的 SCD2 历史管理（有效期、版本标记等）。
- **quality/**  
+- **quality/**
  - 质量检查策略，例如余额一致性、记录数量对齐等。
- **orchestration/**  
+- **orchestration/**
  - 任务调度、任务注册、游标管理（增量窗口）、运行记录追踪。
- **tasks/**  
+- **tasks/**
  - 具体业务任务（订单、支付、会员等），封装了从“取数 → 处理 → 写库 → 记录结果”的完整流程。
- **cli/**  
+- **cli/**
  - 命令行入口，解析参数并启动调度流程。
- **utils/**  
+- **utils/**
  - 杂项工具函数。
- **tests/**  
+- **tests/**
  - 单元测试与集成测试代码。

 ---
@@ -424,32 +424,39 @@ etl_billiards/
 ### 5.2 各层职责（当前设计）

 - **CLI 层 (`cli/`)**
+
  - 解析命令行参数（指定任务列表、Dry-run、覆盖配置项等）。
  - 初始化配置与日志后交由编排层执行。

 - **编排层 (`orchestration/`)**
+
  - `scheduler.py`：根据配置与 CLI 参数选择需要执行的任务，控制执行顺序和并行策略。
  - `task_registry.py`：提供任务注册表，按任务代码创建任务实例（工厂模式）。
  - `cursor_manager.py`：管理增量游标（时间窗口 / ID 游标）。
  - `run_tracker.py`：记录每次任务运行的状态、统计信息和错误信息。

 - **任务层 (`tasks/`)**
+
  - `base_task.py`：定义任务执行模板流程（模板方法模式），包括获取窗口、调用上游、解析 / 校验、写库、更新游标等。
  - `orders_task.py` / `payments_task.py` / `members_task.py`：实现具体任务逻辑（订单、支付、会员）。

 - **加载器 / SCD / 质量层**
+
  - `loaders/`：根据目标表封装 Upsert / Insert / Update 逻辑。
  - `scd/scd2_handler.py`：为维度表提供 SCD2 历史管理能力。
  - `quality/`：执行数据质量检查，如余额对账。

 - **模型层 (`models/`)**
+
  - `parsers.py`：负责数据类型转换（字符串 → 时间戳、Decimal、int 等）。
  - `validators.py`：执行字段级和记录级的数据校验。

 - **API 层 (`api/client.py`)**
+
  - 封装 HTTP 调用，处理重试、超时及分页。

 - **数据库层 (`database/`)**
+
  - 管理数据库连接及上下文。
  - 提供批量插入 / 更新 / Upsert 操作接口。

@@ -509,22 +516,23 @@ etl_billiards/

 ### 6.1 核心功能映射示意

-| 旧版本函数 / 类           | 新版本位置                                             | 说明           |
-|---------------------------|--------------------------------------------------------|----------------|
-| `DEFAULTS` 字典           | `config/defaults.py`                                  | 配置默认值     |
-| `build_config()`          | `config/settings.py::AppConfig.load()`                | 配置加载       |
-| `Pg` 类                   | `database/connection.py::DatabaseConnection`          | 数据库连接     |
-| `http_get_json()`         | `api/client.py::APIClient.get()`                      | API 请求       |
-| `paged_get()`             | `api/client.py::APIClient.get_paginated()`            | 分页请求       |
-| `parse_ts()`              | `models/parsers.py::TypeParser.parse_timestamp()`     | 时间解析       |
-| `upsert_fact_order()`     | `loaders/facts/order.py::OrderLoader.upsert_orders()` | 订单加载       |
-| `scd2_upsert()`           | `scd/scd2_handler.py::SCD2Handler.upsert()`           | SCD2 处理      |
-| `run_task_orders()`       | `tasks/orders_task.py::OrdersTask.execute()`          | 订单任务       |
-| `main()`                  | `cli/main.py::main()`                                 | 主入口         |
+| 旧版本函数 / 类       | 新版本位置                                            | 说明       |
+| --------------------- | ----------------------------------------------------- | ---------- |
+| `DEFAULTS` 字典       | `config/defaults.py`                                  | 配置默认值 |
+| `build_config()`      | `config/settings.py::AppConfig.load()`                | 配置加载   |
+| `Pg` 类               | `database/connection.py::DatabaseConnection`          | 数据库连接 |
+| `http_get_json()`     | `api/client.py::APIClient.get()`                      | API 请求   |
+| `paged_get()`         | `api/client.py::APIClient.get_paginated()`            | 分页请求   |
+| `parse_ts()`          | `models/parsers.py::TypeParser.parse_timestamp()`     | 时间解析   |
+| `upsert_fact_order()` | `loaders/facts/order.py::OrderLoader.upsert_orders()` | 订单加载   |
+| `scd2_upsert()`       | `scd/scd2_handler.py::SCD2Handler.upsert()`           | SCD2 处理  |
+| `run_task_orders()`   | `tasks/orders_task.py::OrdersTask.execute()`          | 订单任务   |
+| `main()`              | `cli/main.py::main()`                                 | 主入口     |

 ### 6.2 典型迁移步骤

 1. **配置迁移**
+
   - 原来在 `DEFAULTS` 或脚本内硬编码的配置，迁移到 `.env` 与 `config/defaults.py`。
   - 使用 `AppConfig.load()` 统一获取配置。

@@ -541,6 +549,7 @@ etl_billiards/
   对比新旧版本导出的数据表和日志，确认一致性。

 3. **自定义逻辑迁移**
+
   - 原脚本中的自定义清洗逻辑 → 放入相应 `loaders/` 或任务类中。
   - 自定义任务 → 在 `tasks/` 中实现并在 `task_registry` 中注册。
   - 自定义 API 调用 → 扩展 `api/client.py` 或单独封装服务类。
@@ -692,3 +701,137 @@ class MyLoader(BaseLoader):

 - 本文已合并原有的快速开始、项目结构、架构说明、迁移指南等内容，可作为当前项目的统一说明文档。
 - 如需在此基础上拆分多份文档，可按章节拆出，例如「快速开始」「架构设计」「迁移指南」「开发扩展」等。
+
+## 11. 运行/调试模式说明
+
+- 生产环境仅保留“任务模式”：通过调度/CLI 执行注册的任务（ETL/ODS），不使用调试脚本。
+- 开发/调试可使用的辅助脚本（上线前可删除或禁用）：
+  - `python -m etl_billiards.scripts.rebuild_ods_from_json`：从本地 JSON 目录重建 `billiards_ods`，用于离线初始化/验证。环境变量：`PG_DSN`（必填）、`JSON_DOC_DIR`（可选，默认 `C:\dev\LLTQ\export\test-json-doc`）、`INCLUDE_FILES`（逗号分隔文件名）、`DROP_SCHEMA_FIRST`（默认 true）。
+- 如需在生产环境保留脚本，请在运维手册中明确用途和禁用条件，避免误用。
+
+## 12. ODS 任务上线指引
+
+- 任务注册：`etl_billiards/database/seed_ods_tasks.sql` 列出了当前启用的 ODS 任务。将其中的 `store_id` 替换为实际门店后执行：
+  ```
+  psql "$PG_DSN" -f etl_billiards/database/seed_ods_tasks.sql
+  ```
+  `ON CONFLICT` 会保持 enabled=true，避免重复。
+- 调度：确认 `etl_admin.etl_task` 中已启用所需的 ODS 任务（任务代码见 seed 脚本），调度器或 CLI `--tasks` 即可调用。
+- 离线回灌：开发环境可用 `rebuild_ods_from_json` 以样例 JSON 初始化 ODS，生产慎用；默认按 `(source_file, record_index)` 去重。
+- 测试：`pytest etl_billiards/tests/unit/test_ods_tasks.py` 覆盖核心 ODS 任务；测试时可设置 `ETL_SKIP_DOTENV=1` 跳过本地 .env 读取。
+
+## 13. 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          |
+
+## 14. ODS 相关环境变量/默认值
+
+- `.env` / 环境变量：
+  - `JSON_DOC_DIR`：ODS 样例 JSON 目录（开发/回灌用）
+  - `ODS_INCLUDE_FILES`：限定导入的文件名（逗号分隔，不含 .json）
+  - `ODS_DROP_SCHEMA_FIRST`：true/false，是否重建 schema
+  - `ETL_SKIP_DOTENV`：测试/CI 时设为 1 跳过本地 .env 读取
+- `config/defaults.py` 中 `ods` 默认值：
+  - `json_doc_dir`: `C:\dev\LLTQ\export\test-json-doc`
+  - `include_files`: `""`
+  - `drop_schema_first`: `True`
+
+---
+
+## 15. DWD 维度 “业务事件”
+
+1. 粒度唯一、原子
+
+- 一张 DWD 表只能有一种业务粒度，比如：
+  - 一条记录 = 一次结账；
+  - 一条记录 = 一段台费流水；
+  - 一条记录 = 一次助教服务；
+  - 一条记录 = 一次会员余额变动。
+- 表里面不能又混“订单头”又混“订单行”，不能一部分是“汇总”，一部分是“明细”。
+- 一旦粒度确定，所有字段都要跟这个粒度匹配：
+  - 比如“结账头表”就不要塞每一行商品明细；
+  - 商品明细就不要塞整单级别的总金额。
+  - 这是 DWD 层最重要的一条。
+
+2. 以业务过程建模，不以 JSON 列表建模
+
+- 先画清楚你真实的业务链路：
+  - 开台 / 换台 / 关台 → 台费流水
+  - 助教上桌 → 助教服务流水 / 废除事件
+  - 点单 → 商品销售流水
+  - 充值 / 消费 → 余额变更 / 充值单
+  - 结账 → 结账头表 + 支付流水 / 退款流水
+  - 团购 / 平台券 → 核销流水
+
+3. 主键明确、外键统一
+
+- 每张 DWD 表必须有业务主键（哪怕是接口给的 id），不要依赖数据库自增。
+- 所有“同一概念”的字段必须统一命名、统一含义：
+  - 门店：统一叫 site_id，都对应 siteProfile.id；
+  - 会员：统一叫 member_id 对应 member_profiles.id，system_member_id 单独一列；
+  - 台桌：统一 table_id 对应 site_tables_master.id；
+  - 结账：统一 order_settle_id；
+  - 订单：统一 order_trade_no 等。
+- 否则后面 DWS、AI 要把表拼起来会非常痛苦。
+
+4. 保留明细，不做过度汇总
+
+- DWD 层的事实表原则上只做“明细级”的数据：
+  - 不要在 DWD 就把“日汇总、周汇总、月汇总”算出来，那是 DWS 的事；
+  - 也不要把多个事件折成一行（例如一张表同时放日汇总+单笔流水）。
+- 需要聚合时，再在 DWS 做主题宽表：
+  - dws_member_day_profile、dws_site_day_summary 等。
+- DWD 只负责细颗粒度的真相。
+
+5. 统一清洗、标准化，但保持可追溯
+
+- 在 DWD 层一定要做的清洗：
+  - 类型转换：字符串时间 → 时间类型，金额统一为 decimal，布尔统一为 0/1；
+  - 单位统一：秒 / 分钟、元 / 分都统一；
+  - 枚举标准化：状态码、类型码在 DWD 里就定死含义，必要时建枚举维表。
+- 同时要保证：
+  - 每条 DWD 记录都能追溯回 ODS：
+- 保留源系统主键；
+  - 保留原始时间 / 原始金额字段（不要覆盖掉）。
+
+6. 扁平化、去嵌套
+
+- JSON 里常见结构是：分页壳 + 头 + 明细数组 + 各种嵌套对象（siteProfile、tableProfile、goodsLedgers…）。
+- DWD 的原则是：
+  - 去掉分页壳；
+  - 把“数组”拆成子表（头表 / 行表）；
+  - 把重复出现的 profile 抽出去做维度表（门店、台、商品、会员……）。
+- 目标是：DWD 表都是二维表结构，不存复杂嵌套 JSON。
+
+7. 模型长期稳定，可扩展
+
+- DWD 的表结构要尽可能稳定，新增需求尽量通过：
+  - 加字段；
+  - 新建事实表 / 维度表；
+  - 在 DWS 做派生指标；
+  - 而不是频繁重构已有 DWD 表结构。
+- 这点跟你后面要喂给 LLM 也很相关：AI 配的 prompt、schema 理解都要尽量少改。