# 审计记录：删除 ODS 层 settlelist 冗余列

## 溯源

- 日期：2026-02-14（Asia/Shanghai）
- Prompt-ID：P20260214-023000
- Prompt 原文：删除 ODS 层 settlement_records / recharge_settlements 的 settlelist jsonb 列（settlelist 与 payload 列数据重复）

## 直接原因

`settlelist` jsonb 列与 `payload` jsonb 列存储内容重复。`payload` 存储完整 API 响应 JSON（已包含 `settleList` 对象），`settlelist` 是入库时额外提取的副本。DWD 加载逻辑已改为从 `payload` 提取，`settlelist` 列不再被消费，属于冗余存储。

## Changed

| 文件/对象 | 变更类型 | 说明 |
|-----------|----------|------|
| `database/migrations/20260214_drop_ods_settlelist.sql` | 新增 | 迁移脚本：DROP COLUMN settlelist（2 张表） |
| `billiards_ods.settlement_records` | DDL | 删除 `settlelist` jsonb 列 |
| `billiards_ods.recharge_settlements` | DDL | 删除 `settlelist` jsonb 列 |
| `tasks/dwd/dwd_load_task.py` | 修改 | FACT_MAPPINGS 中 `dwd_settlement_head_ex.settle_list` 改为从 `payload->'settleList'` 提取 |
| `scripts/ods_columns.json` | 修改 | 移除两表的 `settlelist` 列 |
| `scripts/run_compare_v3_fixed.py` | 修改 | 移除 `classify_ods_only` 中 `settlelist` 的特殊分类 |
| `docs/reports/api_ods_comparison_v3_fixed.md` | 自动生成 | 重新生成比对报告（ODS 独有 49→47，完全对齐 7→9） |
| `docs/bd_manual/ODS/20260214_drop_ods_settlelist.md` | 新增 | BD 手册变更记录 |
| `docs/README.md` | 修改 | 子目录索引新增 ai_audit/、api-reference/、bd_manual/ODS/；test-json-doc/ 标记废弃 |
| `database/README.md` | 修改 | 迁移脚本列表新增 20260214_drop_ods_settlelist.sql |

## Risk / Verify

- 风险：若 DWD 加载逻辑尚未改为从 `payload` 提取 settleList，删列后 DWD 装载将失败 → 已修复（`dwd_load_task.py` 映射改为 `payload->'settleList'`）
- 风险：历史数据中 `payload IS NULL` 的行将永久丢失 settleList 信息
- 验证：迁移已执行，`information_schema.columns` 确认 `settlelist` 列不存在（0 行返回）
- 验证：两表各 71 列（66 业务 + 5 meta），符合预期
- 验证：`payload->'settleList'` 可正常提取（settlement_records: 54937 行，recharge_settlements: 3259 行）
- 验证：比对报告重新生成，ODS 独有从 49 降至 47，settlement_records 和 recharge_settlements 均完全对齐
- 回滚：`ALTER TABLE ... ADD COLUMN settlelist jsonb` + `UPDATE ... SET settlelist = payload->'settleList'`
