# 审计记录：API vs ODS 比对 v3-fixed

## 基本信息

- 日期：2026-02-14（Asia/Shanghai）
- Prompt-ID：P20260214-003000
- 原始原因：用户 Prompt — "还是不准，比如assistant_accounts_master（助教账号主数据）的last_update_name，命名Json里就有，再仔细比对下"
- 直接原因：v3 比对仅从 JSON 样本提取字段，JSON 样本是单条记录快照，可能缺少条件性返回的字段（如 `last_update_name`），导致误报为"ODS独有"。需改用 API 参考文档（.md）的"响应字段详解"章节作为主要字段来源。

## 修改方案

完全重写 `scripts/run_compare_v3_fixed.py`：
1. 从 .md 文档"四、响应字段详解"章节精确提取字段（排除请求参数、跨表关联等章节）
2. JSON 样本作为补充来源（union）
3. 对 settlement_records / recharge_settlements 的 siteProfile 子字段不提取（ODS 中存为 siteprofile jsonb 单列）
4. 对 table_fee_discount_records 的 tableProfile/siteProfile 展开字段正确分类
5. 对 stock_goods_category_tree 的 categoryBoxes 正确识别为 ODS jsonb 列
6. 对所有 ODS 独有字段进行详细分类说明

## Changed

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `scripts/run_compare_v3_fixed.py` | 重写 | 完全重写字段提取和比对逻辑 |
| `docs/reports/api_ods_comparison_v3_fixed.json` | 新建 | JSON 格式比对结果 |
| `docs/reports/api_ods_comparison_v3_fixed.md` | 新建 | Markdown 格式比对报告 |
| `docs/ai_audit/prompt_log.md` | 追加 | 新增 P20260214-003000 条目 |

## 比对结论

- 22 张 ODS 表全部比对
- API 独有字段：0（所有 API 文档中的响应字段在 ODS 中都有对应列）
- ODS 独有字段：51 列，分类如下：
  - API 后续版本新增字段：38 列（文档快照未覆盖，但 ODS 已通过 ETL 动态发现并入库）
  - tableProfile/siteProfile 嵌套对象展开字段：8 列（table_fee_discount_records）
  - ODS 额外添加的 tenant_id：2 列（assistant_cancellation_records、payment_transactions）
  - ODS jsonb 列（settlelist）：2 列（settlement_records、recharge_settlements）
  - ODS 后续版本新增字段：1 列（site_tables_master.order_id）
- 完全对齐表：7 张（assistant_accounts_master、refund_transactions、platform_coupon_redemption_records、stock_goods_category_tree、goods_stock_movements、goods_stock_summary、site_tables_master 除 order_id 外）
- 无需 ALTER TABLE

## Risk / Verify

- 风险：纯分析脚本和报告，无运行时影响，不修改数据库或 ETL 逻辑
- 验证：
  1. 确认 `assistant_accounts_master` 的 `last_update_name` 被正确识别为匹配字段（62:62 完全对齐）
  2. 确认 API 独有字段总数为 0
  3. 确认 ODS 独有字段全部有分类说明

## Change Impact Review

- 判定：**无逻辑改动**
- 本次变更为纯分析脚本（一次性工具）和报告文档，不涉及 ETL Connector、业务规则、数据处理逻辑、API 行为或数据库 schema
- 文档同步评估：
  - `product.md` — 无需更新（产品功能未变）
  - `tech.md` — 无需更新（技术栈未变）
  - `structure.md` — 无需更新（目录结构未变，临时分析脚本不列入）
  - `README.md` — 无需更新（运行方式未变）
  - `docs/bd_manual/` — 无需更新（无表结构变更）
  - `gui/README.md` / `scripts/` / `tasks/` / `database/` / `tests/` — 均无需更新
- 回归范围：无（纯分析产出，不影响任何运行时代码路径）
- 建议验证：`python scripts/run_compare_v3_fixed.py` 确认输出 API独有=0

<!--
AI_CHANGELOG:
- 日期: 2026-02-14
- Prompt: P20260214-003000 — v3 比对不准确，重写为 v3-fixed
- 直接原因: 创建审计记录
- 变更摘要: 新建审计记录文件，记录 v3-fixed 比对的完整变更信息
- 风险与验证: 纯文档，无运行时影响
-->