整理项目

2025-12-09 05:42:57 +08:00
parent 561c640700
commit 0c29bd41f8
2 changed files with 334 additions and 75 deletions
--- a/README.md
+++ b/README.md
@@ -1,88 +1,66 @@
-# 飞球 ETL 系统
+# 飞球 ETL 系统（ODS→DWD 全流程说明）

-面向门店业务的 ETL 流水线：从上游 API 拉取订单/支付/会员/库存等 JSON，先落地 ODS，随后清洗装载 DWD（含 SCD2 维度、事实增量），并提供质量校验与回归验证工具。
+本项目实现门店业务的 ETL 流水线：拉取/或离线灌入上游 JSON，落地 ODS，清洗装载 DWD（含 SCD2 维度、事实增量），并提供质量校验报表。

-## 功能要点
- 双层形态：ODS 原始保留 + DWD 清洗标准化，支持回放与重载。
- 任务调度：ETLScheduler 统一管理任务、日志、失败隔离，CLI 友好。
- 配置体系：默认值 + .env + CLI 覆盖，便于多环境运行。
- 批量入库：通用 ODS Loader / SCD2 维度合并 / 事实增量写入。
- 回归校验：示例 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) 安装依赖：
+## 快速运行（本地离线示例 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
-   # 开发模式：pip install -e .
   ```
-3) 配置 .env（示例关键项）：
+3) 一键离线回放（ODS→DWD→质检）  
   ```bash
-   PG_DSN=postgresql://user:pwd@host:5432/LLZQ-test
-   API_BASE=https://api.example.com
-   API_TOKEN=your_token
-   STORE_ID=2790685415443269
-   EXPORT_ROOT=C:\dev\LLTQ\export\JSON
-   LOG_ROOT=C:\dev\LLTQ\export\LOG
-   INGEST_SOURCE_DIR=C:\dev\LLTQ\export\test-json-doc
-   ```
-4) 初始化库表：
-   ```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"
+   # 初始化 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`

-## 运行与数据流
- CLI 解析参数 -> AppConfig.load 合并配置 -> ETLScheduler 创建 DB/API/日志上下文 -> 实例化任务 -> 拉取/清洗/写入。
- ODS 任务：调用 API，分页提取，字段解析后批量 upsert；payload 保留原始 JSON。
- DWD 任务：维度表做 SCD2，事实表按时间水位增量写入。
+## 数据与目录约定
+- 示例数据目录：`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。

-## 测试与回归
- 单测/集成：pytest 或 python scripts/run_tests.py --suite online。
- 离线模式：TEST_MODE=OFFLINE TEST_JSON_ARCHIVE_DIR=... pytest tests/unit/test_etl_tasks_offline.py。
- 数据库连通：python scripts/test_db_connection.py --dsn <PG_DSN> --query "SELECT 1"。
+## 模块与主要文件
+- 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/任务文件的备份版本。

-## 其他提示
- .env.example 罗列全部配置；config/defaults.py 给出默认值与任务窗口。
- loaders/ods/generic.py 支持自定义主键/冲突列；	asks/manual_ingest_task.py 可将示例 JSON 快速灌入对应 ODS 表。
- 添加新任务：在 	asks/ 中实现并在 orchestration/task_registry.py 注册。
+## 当前进展（2025-12-09）
+- ODS & DWD 已全量跑通，示例 JSON 全部灌入；DWD 维度/事实行数与 ODS 匹配。  
+- 分类维度已展平大类+子类：`dim_goods_category` 行数 26（大类 pid=0，子类 pid 指向大类，category_level 已赋值）。  
+- 全空字段多因源数据为空；若需补充请先确认上游是否提供。

-## ODS 任务与调度使用
- 注册：etl_admin.etl_task 已启用 INIT_ODS_SCHEMA、MANUAL_INGEST（store_id=2790685415443269，可按需追加其他任务）。
- 示例数据目录：默认 C:\dev\LLTQ\export\test-json-doc（可在 .env 的 INGEST_SOURCE_DIR 覆盖）。
- 一键重建+灌入：
-  `bash
-  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。
+## 过期/可精简内容
+- `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 与映射。
--- a/README_FULL.md
+++ b/README_FULL.md
@@ -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`）。
+
+---
+
+> 以上为合并后的单点说明文档。若需拆分为「快速开始 / 架构设计 / 迁移指南 / 开发扩展」等多份文档，可按章节直接拆分。