阶段性更新

etl_billiards/README.md

@@ -219,6 +219,42 @@ python scripts/run_tests.py --preset offline_realdb
 python scripts/run_tests.py --list-presets   # 查看或自定义 scripts/test_presets.py
 ```
 
+#### 3.3.2 脚本化测试组合（`run_tests.py` / `test_presets.py`）
+
+- `scripts/run_tests.py` 是 pytest 的统一入口：自动把项目根目录加入 `sys.path`，并提供 `--suite online/offline/integration`、`--tests`（自定义路径）、`--mode`、`--db-dsn`、`--json-archive`、`--json-temp`、`--keyword/-k`、`--pytest-args`、`--env KEY=VALUE` 等参数，可以像搭积木一样自由组合；
+- `--preset foo` 会读取 `scripts/test_presets.py` 内 `PRESETS["foo"]` 的配置，并叠加到当前命令；`--list-presets` 与 `--dry-run` 可用来审阅或仅打印命令；
+- 直接执行 `python scripts/test_presets.py` 可依次运行 `AUTO_RUN_PRESETS` 中列出的预置；传入 `--preset x --dry-run` 则只打印对应命令。
+
+`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` | 说明性文字，便于描述场景 |
+
+示例：`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 与生产回放脚本一致。
+
+#### 3.3.3 数据库连通性快速检查
+
+`python scripts/test_db_connection.py` 提供最轻量的 PostgreSQL 连通性检测：默认使用 `TEST_DB_DSN`（也可传 `--dsn`），尝试连接并执行 `SELECT 1 AS ok`（可通过 `--query` 自定义）。典型用途：
+
+```bash
+# 读取 .env/环境变量中的 TEST_DB_DSN
+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"
+```
+
+脚本返回 0 代表连接与查询成功；若返回非 0，可结合第 8 章“常见问题排查”的数据库章节（网络、防火墙、账号权限等）先定位问题，再运行完整 ETL。
+
 ---
 
 ## 4. 项目结构与文件说明
@@ -452,6 +488,19 @@ etl_billiards/
 - API 请求失败时按配置进行重试，超过重试次数记录错误并终止该任务。
 - 所有错误被记录到日志和运行追踪表，便于事后排查。
 
+### 5.6 ODS + DWD 双阶段策略（新增）
+
+为了支撑回溯/重放与后续 DWD 宽表构建，项目新增了 `billiards_ods` Schema 以及一组专门的 ODS 任务/Loader：
+
+- **ODS 表**：`billiards_ods.ods_order_settle`、`ods_table_use_detail`、`ods_assistant_ledger`、`ods_assistant_abolish`、`ods_goods_ledger`、`ods_payment`、`ods_refund`、`ods_coupon_verify`、`ods_member`、`ods_member_card`、`ods_package_coupon`、`ods_inventory_stock`、`ods_inventory_change`。每条记录都会保存 `store_id + 源主键 + payload JSON + fetched_at + source_endpoint` 等信息。
+- **通用 Loader**：`loaders/ods/generic.py::GenericODSLoader` 统一封装了 `INSERT ... ON CONFLICT ...` 与批量写入逻辑，调用方只需提供列名与主键列即可。
+- **ODS 任务**：`tasks/ods_tasks.py` 内通过 `OdsTaskSpec` 定义了一组任务（`ODS_ORDER_SETTLE`、`ODS_PAYMENT`、`ODS_ASSISTANT_LEDGER` 等），并在 `TaskRegistry` 中自动注册，可直接通过 `python -m cli.main --tasks ODS_ORDER_SETTLE,ODS_PAYMENT` 执行。
+- **双阶段链路**：
+  1. 阶段 1（ODS）：调用 API/离线归档 JSON，将原始记录写入 ODS 表，保留分页、抓取时间、来源文件等元数据。
+  2. 阶段 2（DWD/DIM）：后续订单、支付、券等事实任务将改为从 ODS 读取 payload，经过解析/校验后写入 `billiards.fact_*`、`dim_*` 表，避免重复拉取上游接口。
+
+> 新增的单元测试 `tests/unit/test_ods_tasks.py` 覆盖了 `ODS_ORDER_SETTLE`、`ODS_PAYMENT` 的入库路径，可作为扩展其他 ODS 任务的模板。
+
 ---
 
 ## 6. 迁移指南（从旧脚本到当前项目）