Neo-ZQYY/docs/audit/changes/2026-02-13__api-ods-comparison-v2.md

审计记录：API vs ODS 对比 v2

• 日期：2026-02-13（Asia/Shanghai）
• Prompt-ID：P20260213-223000
• 原始原因：用户要求用 API 参考文档比对数据库 ODS 实际表结构（不依赖 DDL），生成对比报告和 ALTER SQL。上一次运行结果不准确，要求重做。
• 直接原因：前次比对脚本存在 bug（stock_goods_category_tree 嵌套结构未正确解析），需重写脚本并重新生成报告。

改动方案

1. 重写 scripts/compare_api_ods_v2.py：
   • 从 docs/api-reference/*.md 的 JSON 样例提取字段
   • 查询 PostgreSQL billiards_ods 实际列
   • 处理三种特殊结构：标准 data.list、嵌套 siteProfile+settleList、数组包装 goodsCategoryList
   • 输出 JSON + Markdown 报告
2. 运行脚本，生成 docs/reports/api_ods_comparison_v2.json 和 .md

结论

• 22 张 ODS 表全部与 API JSON 字段对齐（API 字段 ⊆ ODS 列）
• 0 张漂移，无需 ALTER SQL
• 3 张跳过（settlement_ticket_details 标记 skip，role_area_association / tenant_member_balance_overview 无 ODS 表）
• ODS 独有列共 97 个（非元列），均为 ETL 派生列或历史新增字段，API 样例中不存在但不影响数据完整性

Changed

文件	操作
scripts/compare_api_ods_v2.py	重写（完整脚本）
docs/reports/api_ods_comparison_v2.json	新建（JSON 报告）
docs/reports/api_ods_comparison_v2.md	新建（Markdown 报告）

Risk / Verify

• 风险：纯分析脚本 + 报告文档，无运行时影响，不修改数据库
• 验证：
  1. python scripts/compare_api_ods_v2.py 输出 "对齐 22 / 漂移 0"
  2. 检查 docs/reports/api_ods_comparison_v2.md 汇总表中无 ⚠️ 漂移行
  3. JSON 报告中所有 api_only 数组为空