39 lines
1.8 KiB
Markdown
39 lines
1.8 KiB
Markdown
# 审计记录：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` 数组为空
|