46 lines
2.8 KiB
Markdown
46 lines
2.8 KiB
Markdown
# 审计记录：ODS vs Summary 字段比对
|
||
|
||
- 日期：2026-02-14（Asia/Shanghai）
|
||
- Prompt-ID：P20260214-150000 / P20260214-160000
|
||
- 原始原因：用户要求通过直接查询 PostgreSQL `billiards_ods` schema，与 `docs/api-reference/summary/` 下 25 个 MD 文档的"响应字段详解"章节进行逐表字段比对，输出差异项。
|
||
- 直接原因：需要验证 ODS 表结构与 API 文档的一致性，发现潜在的字段遗漏或文档过时问题。
|
||
|
||
## Changed
|
||
|
||
- `scripts/compare_ods_vs_summary_v2.py`（新建）— 比对脚本最终版，支持 camelCase/snake_case/连写小写三重匹配
|
||
- `docs/reports/ods_vs_summary_comparison_v2.json`（新建）— JSON 格式比对报告
|
||
- `scripts/compare_ods_vs_summary.py`（v1，待清理）— 初版脚本，已被 v2 替代
|
||
- `docs/reports/ods_vs_summary_comparison.json`（v1，待清理）— 初版报告，已被 v2 替代
|
||
|
||
## 比对结果摘要
|
||
|
||
- 完全匹配：10 张表
|
||
- 有差异：13 张表（主要原因：siteProfile/tableProfile jsonb 列、remark 字段 MD 缺失、tenant_id ODS 入库时添加、start_time/end_time 为请求参数、settlement_ticket_details 的 46 个嵌套 JSON 子字段）
|
||
- 无 ODS 表：2 个（member_consumption_statistics、tenant_member_balance_overview，聚合查询 API 无需 ODS 表）
|
||
|
||
## Risk / Verify
|
||
|
||
- 风险：纯分析/报告任务，无运行时影响，无 DB schema 变更，无逻辑改动
|
||
- 验证：`python scripts/compare_ods_vs_summary_v2.py` 可重复运行验证结果
|
||
- 回归范围：无
|
||
|
||
---
|
||
|
||
## 追加：P20260214-170000 — REQUEST_PARAMS 误报修复
|
||
|
||
- 日期：2026-02-14（Asia/Shanghai）
|
||
- Prompt-ID：P20260214-170000
|
||
- 原始原因：用户反馈 `assistant_accounts_master` 的 `end_time`/`start_time` 在 MD 文档中有收录，但脚本报告为"ODS有/MD无"，结果错误。
|
||
- 直接原因：`REQUEST_PARAMS` 全局黑名单包含 `start_time`/`end_time`/`starttime`/`endtime`，`is_request_param` 对 MD 侧字段做了过滤但 ODS 侧未过滤，导致不对称假差异。这些字段在 `assistant_accounts_master`、`group_buy_packages`、`member_stored_value_cards` 中是真正的响应业务字段。
|
||
|
||
### Changed
|
||
|
||
- `scripts/compare_ods_vs_summary_v2.py` — 从 `REQUEST_PARAMS` 移除 4 个值，添加 CHANGE 标记注释
|
||
- `docs/reports/ods_vs_summary_comparison_v2.json` — 重新生成（完全匹配从 10→12）
|
||
|
||
### Risk / Verify
|
||
|
||
- 风险：修改了比对脚本的过滤逻辑，可能导致原本被正确过滤的请求参数重新出现
|
||
- 验证：已运行脚本确认 `assistant_accounts_master`(62/62)、`member_stored_value_cards`(75/75) 变为完全匹配；`group_buy_packages` 不再误报 `start_time`/`end_time`
|
||
- 安全性：`extract_response_fields` 的章节限定逻辑（仅提取"响应字段详解"章节）已能排除请求参数中的 `startTime`/`endTime`，无需在 `REQUEST_PARAMS` 中重复过滤
|