# 审计记录：JSON 样本 vs MD 文档全面排查

- 日期：2026-02-14（Asia/Shanghai）
- Prompt-ID：P20260214-044500
- 原始原因：用户指出 md 文档和 json 数据不对应，要求全面排查所有 API 参考文档与 JSON 样本的字段一致性
- 直接原因：table_fee_transactions 的 3 个字段（activity_discount_amount、order_consumption_type、real_service_money）被报告为 ODS 独有，用户认为 JSON 中存在。经查证这些字段确实不在当前 JSON 样本中，但需要全面验证所有表的 .md 文档是否与 JSON 样本一致。

## Changed

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `scripts/check_json_vs_md.py` | 新建 | JSON 样本 vs .md 文档字段比对脚本 |
| `docs/reports/json_vs_md_gaps.json` | 新建 | 比对结果（JSON 格式） |

## 比对结论

- 24 个表全部通过：JSON→MD 缺失字段数 = 0
- 4 个表有 MD 多于 JSON 的情况（条件性字段，JSON 快照未包含），属正常现象：
  - assistant_accounts_master: md 多 1 个（last_update_name）
  - assistant_service_records: md 多 2 个（assistantteamname, real_service_money）
  - stock_goods_category_tree: md 多 1 个（total）
  - tenant_member_balance_overview: md 多 3 个（balance, cardtypename, principalbalance）
- 结论：.md 文档与 JSON 样本一致，无需修补文档

## 脚本修复记录

开发过程中发现并修复 3 个 bug：
1. `CROSS_REF_HEADERS` 包含 `"type"` 导致 group_buy_packages 的 type 业务字段被过滤 → 移除
2. `WRAPPER_FIELDS` 过滤逻辑跳过 siteProfile/tableProfile（它们是有效 ODS jsonb 列）→ 添加例外
3. role_area_association JSON 有 roleAreaRelations 包装器 → 添加特殊提取逻辑

## Risk / Verify

- 风险：纯分析脚本和报告，无运行时影响
- 验证：`python scripts/check_json_vs_md.py` 输出 "0 个有 JSON→MD 缺失"
- 回归范围：无（不影响 ETL 管线或数据库）