49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# 审计记录：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`
|