metric-reconciliation

指标对账

使用时机

• 两个仪表板或报告显示的同一 KPI 数值不同
• 数据管道更新后，某项指标出现意外变化
• 利益相关方质疑某个数值，需要权威说明
• 准备合并或弃用旧版报告数据源
• 帮助分析师熟悉新的数据模型，并与旧模型进行验证

流程

1. 定义指标和范围 — 确认确切定义（分子、分母、筛选条件、时区）以及调查期间。定义不一致是造成差异的最常见原因。
2. 从两个数据源提取数值 — 从每个数据源提取相同期间的指标数值。记录绝对值、行数，以及所用的查询或计算路径。
3. 计算差距 — 计算绝对差值和百分比差距。如果差距在约定的容差范围内（例如 ±0.1%），则记录为可接受并结束处理。容差指南请参阅 references/reconciliation_patterns.md。
4. 追踪计算路径 — 逐步检查每个数据源的查询或管道。常见的差异点包括：联接类型不同、筛选顺序不同、空值处理方式不同、日期截断方式不同或去重逻辑不同。
5. 确定根本原因 — 使用 references/metric_discrepancy_guide.md 对原因进行分类（定义不匹配、数据新鲜度、聚合粒度、计算错误）。通过代码片段或查询摘录记录差异点。
6. 解决并记录 — 修正计算方式或确定规范数据源，然后填写 assets/reconciliation_report_template.md 并与利益相关方分享。

此技能所需的输入

• 指标名称和业务定义（分子、分母及任何已知变体）
• 对两个数据源的访问权限（查询、仪表板 SQL 或原始数据）
• 出现差异的时间段
• 行数或记录级数据，以便在需要时逐行比较
• 管道、架构或业务规则近期发生的任何已知变更

输出

• assets/reconciliation_report_template.md — 已完成的报告，展示数据源 A 与数据源 B 的对比、差距、根本原因和解决状态
• 修正后的查询或管道变更（如果发现错误）
• 已记录的容差协议（如果差距可接受）