Neo-ZQYY/docs/audit/changes/2026-02-14__drop-ods-settlelist.md

审计记录：删除 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'