# 审计记录：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`