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