init: 项目初始提交 - NeoZQYY Monorepo 完整代码

apps/etl/pipelines/feiqiu/docs/database/DWD/changes/2026-02-13_ddl_sync_dwd.md

@@ -0,0 +1,85 @@
+# DWD 层 DDL 同步修正 — 变更记录
+
+> 结构性变更：修正 1 项差异（补充 1 个缺失字段定义）
+
+## 溯源
+
+- 日期：2026-02-13（Asia/Shanghai）
+- 工具：`scripts/compare_ddl_db.py --schema billiards_dwd --ddl-path database/schema_dwd_doc.sql`
+- Direct cause：DDL 对比脚本发现 `database/schema_dwd_doc.sql` 与数据库 `billiards_dwd` schema 实际状态存在 1 项差异，以数据库为准修正 DDL 文件。
+
+## 变更内容
+
+| Schema | 表名 | 操作 | 字段 | DDL 原定义 | 数据库实际 | 说明 |
+|--------|------|------|------|-----------|-----------|------|
+| `billiards_dwd` | `dwd_refund_ex` | DDL 补充字段 | `check_status` | — | `INTEGER` | 数据库中有但 DDL 中未定义（解析器 bug 导致遗漏，已修复） |
+
+## 变更原因
+
+1. `dwd_refund_ex.check_status`：该字段实际已存在于数据库中，对应 ODS 层 `refund_transactions.check_status`（退款审核状态）
+2. DDL 解析器存在 bug 导致该字段在先前对比中被遗漏，修复解析器后重新对比发现此差异
+3. 该字段由 DWD 加载任务从 ODS 层 `refund_transactions` 映射而来
+
+## 影响范围
+
+| 影响对象 | 影响程度 | 说明 |
+|----------|----------|------|
+| ETL 加载任务 | 无影响 | 本次仅修正 DDL 文档，不涉及数据库结构变更 |
+| 后端 API | 无影响 | DDL 文件为文档性质，不影响运行时 |
+| 小程序字段映射 | 无影响 | 小程序不直接读 DWD 层 |
+| DWD 表级文档 | ⚠️ 需同步 | `BD_manual_dwd_refund_ex.md` 字段列表应包含 `check_status` |
+| ODS→DWD 映射 | 无影响 | `check_status` 已在 DWD 加载映射中正确配置 |
+
+**注意**：本次变更仅修正 DDL 文件（文档同步），数据库结构未发生任何变更。
+
+## 回滚策略
+
+本次为 DDL 文件修正（文档同步），无需数据库回滚。若需恢复 DDL 文件，使用 Git 回退即可：
+
+```bash
+git checkout HEAD~1 -- database/schema_dwd_doc.sql
+```
+
+若未来需要将数据库结构回退（不推荐）：
+
+```sql
+-- 删除 check_status 列（会丢失已有数据）
+ALTER TABLE billiards_dwd.dwd_refund_ex DROP COLUMN check_status;
+```
+
+## 验证 SQL
+
+```sql
+-- 1) 确认 dwd_refund_ex.check_status 存在且类型为 integer
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_schema = 'billiards_dwd'
+  AND table_name = 'dwd_refund_ex'
+  AND column_name = 'check_status';
+-- 预期：1 行，data_type = 'integer'
+
+-- 2) 确认 ODS 层对应字段也存在（数据来源一致性）
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_schema = 'billiards_ods'
+  AND table_name = 'refund_transactions'
+  AND column_name = 'check_status';
+-- 预期：1 行，data_type = 'integer'
+
+-- 3) 确认 dwd_refund_ex 表当前总列数
+SELECT count(*) AS total_columns
+FROM information_schema.columns
+WHERE table_schema = 'billiards_dwd'
+  AND table_name = 'dwd_refund_ex';
+-- 预期：列数包含 check_status
+
+-- 4) 确认修正后 DDL 与数据库零差异（通过对比脚本验证）
+-- python scripts/compare_ddl_db.py --schema billiards_dwd --ddl-path database/schema_dwd_doc.sql
+-- 预期：0 项差异
+```
+
+## 关联变更
+
+- ODS 层同步修正：`docs/database/ODS/changes/2026-02-13_ddl_sync_ods.md`（`refund_transactions.check_status` 同步补充）
+- DDL 文件：`database/schema_dwd_doc.sql`
+- 对比结果：`docs/database/ddl_compare_results.md`

apps/etl/pipelines/feiqiu/docs/database/DWD/changes/20260214_drop_dwd_settle_list.md

@@ -0,0 +1,94 @@
+# DWD 层删除 dwd_settlement_head_ex.settle_list 冗余列 — 变更记录
+
+> 结构性变更：删除 1 张表的 1 个 JSONB 列
+
+## 溯源
+
+- 日期：2026-02-14（Asia/Shanghai）
+- Prompt：P20260214-040000 — 删除 DWD 层 dwd_settlement_head_ex 的 settle_list JSONB 列
+- Direct cause：`settle_list` 列存储结算明细 JSON，与 ODS 层 `payload` 中的 `settleList` 对象完全重复。ODS 层 `settlelist` 列已在 `20260214_drop_ods_settlelist.sql` 中删除，DWD 层该列同样冗余。结算明细可随时从 ODS `payload->'settleList'` 按需提取。
+
+## 变更内容
+
+| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
+|--------|------|------|------|--------|------|
+| `billiards_dwd` | `dwd_settlement_head_ex` | DROP COLUMN | `settle_list` | `JSONB` | 结算明细 JSON，与 ODS payload 中 settleList 重复 |
+
+### Before / After
+
+- Before：31 个字段（order_settle_id PK + 29 个业务字段 + settle_list JSONB）
+- After：30 个字段（order_settle_id PK + 29 个业务字段）
+
+## 变更原因
+
+1. ODS 层 `settlement_records.payload`（jsonb）已存储完整 API 响应，其中包含 `settleList` 对象
+2. ODS 层 `settlelist` 列已在同日迁移 `20260214_drop_ods_settlelist.sql` 中删除
+3. DWD 层 `settle_list` 是从 ODS `settlelist` 映射而来的副本，上游已删除，DWD 层同步清理
+4. DWD 加载映射（`dwd_load_task.py` FACT_MAPPINGS）中 `settle_list` 映射已移除
+
+## 影响范围
+
+| 影响对象 | 影响程度 | 说明 |
+|----------|----------|------|
+| DWD 加载任务 | ✅ 已处理 | `dwd_load_task.py` FACT_MAPPINGS 中 `dwd_settlement_head_ex` 的 `settle_list` 映射已移除 |
+| DWS 汇总层 | 无影响 | DWS 层不消费 `settle_list` 列 |
+| API 契约 | 无影响 | API 响应结构不变 |
+| 小程序 | 无影响 | 小程序不直接读 DWD 层 |
+| BD 手册 | ✅ 已处理 | `BD_manual_dwd_settlement_head_ex.md` 字段列表已不含 `settle_list` |
+
+## 回滚策略
+
+```sql
+-- 1) 恢复列结构
+ALTER TABLE billiards_dwd.dwd_settlement_head_ex ADD COLUMN settle_list JSONB;
+
+-- 2) 从 ODS payload 回填数据
+UPDATE billiards_dwd.dwd_settlement_head_ex e
+SET settle_list = o.payload->'settleList'
+FROM billiards_ods.settlement_records o
+WHERE e.order_settle_id = o.id;
+```
+
+**注意事项**：
+- 回滚后 `settle_list` 列数据为 NULL，必须执行回填 UPDATE
+- 若 ODS 中 `payload IS NULL` 的行，对应 DWD 行的 `settle_list` 将为 NULL（无法恢复）
+
+## 验证 SQL
+
+```sql
+-- 1) 确认 settle_list 列已不存在
+SELECT column_name
+FROM information_schema.columns
+WHERE table_schema = 'billiards_dwd'
+  AND table_name = 'dwd_settlement_head_ex'
+  AND column_name = 'settle_list';
+-- 预期：0 行
+
+-- 2) 确认表当前列数
+SELECT count(*) AS total_columns
+FROM information_schema.columns
+WHERE table_schema = 'billiards_dwd'
+  AND table_name = 'dwd_settlement_head_ex';
+-- 预期：30（order_settle_id + 29 个业务字段）
+
+-- 3) 确认 ODS payload 中 settleList 仍可按需提取
+SELECT count(*)
+FROM billiards_ods.settlement_records
+WHERE payload IS NOT NULL AND payload->'settleList' IS NOT NULL;
+-- 预期：> 0（结算明细数据仍可从 ODS 获取）
+
+-- 4) 确认 DWD 表数据完整性（主表-扩展表行数一致）
+SELECT
+  (SELECT count(*) FROM billiards_dwd.dwd_settlement_head) AS main_count,
+  (SELECT count(*) FROM billiards_dwd.dwd_settlement_head_ex) AS ex_count;
+-- 预期：两个计数相等
+```
+
+## 迁移文件
+
+`database/migrations/20260214_drop_dwd_settle_list.sql`
+
+## 关联变更
+
+- ODS 层同日变更：`database/migrations/20260214_drop_ods_settlelist.sql`（删除 `settlement_records.settlelist` 和 `recharge_settlements.settlelist`）
+- BD 手册 ODS 变更记录：`docs/database/ODS/changes/20260214_drop_ods_settlelist.md`