Neo-ZQYY/docs/audit/changes/2026-02-14__ods-vs-summary-comparison.md

审计记录：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 中重复过滤