# 审计记录：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` 数组为空