Neo-ZQYY/docs/audit/changes/2026-02-14__json-vs-md-audit.md

审计记录：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 Connector 或数据库）