在准备环境前提交次全部更改。

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

@@ -0,0 +1,48 @@
+# 审计记录：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`