审计记录：API JSON 字段 vs ODS 表列对比

日期：2026-02-13 (Asia/Shanghai)
Prompt-ID：P20260213-210000
原始 Prompt：

用新梳理的API返回的JSON文档docs\api-reference，比对数据库的ODS层是否和Json一致? 给我个对比结论文档。将不同的内容，通过SQL语句，将ODS各表与返回的JSON字段结构对齐。（续接：不是，你需要查询数据库，不要依赖DDL）

直接原因

用户需要验证 ODS 层数据库表结构是否与上游 API 返回的 JSON 字段一致。方案：编写 Python 脚本查询 billiards_ods schema 的 information_schema.columns，解析 docs/api-reference/endpoints/*.md 中的响应字段表，做 camelCase→snake_case 归一化匹配。

修改文件清单

文件	操作	说明
`scripts/compare_api_ods.py`	新建	比对脚本（查询 DB + 解析 MD + 归一化匹配）
`docs/reports/api_ods_comparison.md`	新建	Markdown 对比报告
`docs/reports/api_ods_comparison.json`	新建	JSON 格式对比数据
`database/migrations/20260213_align_ods_with_api.sql`	新建	迁移文件（结论：无需变更）
`docs/ai_audit/prompt_log.md`	追加	Prompt 日志
`docs/ai_audit/changes/2026-02-13__api-ods-comparison.md`	新建	本审计记录

比对结论

22 张 ODS 表全部与 API JSON 字段对齐，无需任何 ALTER 操作
大量字段差异为 camelCase vs lowercase 命名风格差异，归一化后全部匹配
stock_goods_category_tree 的 2 个"缺失"为响应包装层字段（goodsCategoryList/total），ODS 已正确展开存储
66 个 ODS "多余"列为 ETL 框架自行添加的辅助列（如 tenant_id、settlelist、real_service_money 等）

风险评估

风险等级：低
本次无逻辑改动，无数据库结构变更，无 ETL 行为变化
新建的比对脚本为只读分析工具，不修改任何数据
回归范围：无
验证方式：python scripts/compare_api_ods.py 重新执行确认输出一致

回滚要点

无需回滚（未执行任何数据库变更）。如需清理：

删除 scripts/compare_api_ods.py
删除 docs/reports/api_ods_comparison.md 和 .json
删除 database/migrations/20260213_align_ods_with_api.sql

2.3 KiB Raw Permalink Blame History Unescape Escape