财务说这个月的收入是 1,204 万，运营的后台显示 1,238 万。差额 34 万，占 2.8%，两边都不认为自己错。技术团队被拉进来"核对一下"，结果花了三天，发现问题不在数据，而在两边对"收入"的定义不同：一边含税不含退款，一边含退款不含税。
这类争执的典型走向是：先查数据、再查 SQL、最后才想到查定义。而定义恰恰是唯一一处必须在动手之前就问清的东西，因为数据量再大、SQL 写得再对，只要定义不同，两边永远对不上。
1. 三个层次的对不上
| 层次 | 差异幅度 | 排查手段 |
|---|---|---|
| 定义不同 | 通常 1%–10%，稳定 | 对口径文档 |
| 计算过程不同 | 小幅，随数据量变化 | 逐层比对中间结果 |
| 数据本身不同 | 可能任意幅度 | 抽样比对原始记录 |
第一层的特征是"差额稳定、可解释"，因为它是两个固定公式的差。
第二层的特征是"差额随规模变化"，比如一边去重一边没去重、一边按天截断一边按自然月。
第三层的特征是"能定位到具体记录"，可以逐条列出差异。
排查顺序必须是先定义、再过程、最后数据。 反过来做，会在数据层耗掉大量时间，最后发现白干。
2. 把定义写成可对账的形式
| 要素 | 例子 |
|---|---|
| 时间范围 | 自然月（含首尾）还是按结算周期 |
| 计量对象 | 下单、支付、发货、签收中的哪一个 |
| 金额口径 | 含税/不含税、含退款/不含退款、含运费/不含 |
| 去重规则 | 按订单号还是按支付流水号 |
| 边界处理 | 跨月退款算在哪个月 |
这类争执还有一个组织特征：两边的负责人都不愿意先改自己的口径，因为改口径意味着"之前的数字是错的"。所以仲裁必须由第三方主持，并且明确"改口径不是认错，是统一术语"。
第二项最容易被忽略："收入"这个词在四个时间点上都能被定义，而它们对应的数字完全不同。所以对账第一步不是查 SQL，而是问"你这张报表统计的是哪个时点的事件"。
// 口径卡：一张报表一张卡，写不清就对不了账
report: 收入日报
time_range: 自然日 00:00:00–23:59:59（本地时区）
event: 支付成功（pay_status = SUCCESS 的时间戳）
amount: 实收金额 = 订单金额 - 优惠 - 已退款（含税）
dedup: 按 pay_no 去重，同一订单多次支付只计一次
boundary: 跨日退款按退款发生日冲减（负值计入当日）
3. 差额要能被解释，而不是被抹平
| 差额类型 | 处理 |
|---|---|
| 已知口径差 | 写进文档，报表标注 |
| 已知过程差 | 修正计算逻辑 |
| 未知数据差 | 抽样定位到记录 |
| 无法解释 | 保留为待查项，不强行对齐 |
差额能被解释到什么程度，取决于中间结果的可得性。所以设计报表时就该留下中间层：
-- 留中间层：每一层都能单独对账，差额可定位到层
WITH paid AS ( -- 第一层：支付成功记录
SELECT order_id, pay_no, amount, paid_at FROM pay WHERE status = 'SUCCESS'
), dedup AS ( -- 第二层：按 pay_no 去重
SELECT DISTINCT pay_no, order_id, amount, paid_at FROM paid
), refund AS ( -- 第三层：扣减退款
SELECT d.*, COALESCE(r.refunded, 0) AS refunded
FROM dedup d LEFT JOIN ref_daily r ON r.order_id = d.order_id
)
SELECT DATE(paid_at) AS d, SUM(amount - refunded) AS revenue FROM refund GROUP BY d;
-- 对账时逐层比：第一层差 → 数据问题；第二层差 → 去重规则；第三层差 → 退款口径
第四项是关键的职业判断："强行对齐"会让两边都失去可信度。正确做法是把无法解释的差额保留为一条显式的待查项，附上金额与影响范围。
4. 仲裁的流程与责任
| 步骤 | 产出 | 负责人 |
|---|---|---|
| 1 各自写出定义 | 口径卡 | 各报表负责人 |
| 2 对比定义 | 差异清单 | 技术（中立方） |
| 3 定唯一口径 | 口径文档 v1 | 业务决策人 |
| 4 修正实现 | 变更记录 | 各实现方 |
| 5 建立对账机制 | 每日差额告警 | 技术 |
口径文档还有一条实用要求：必须写明"这个口径不能用来做什么"。比如"收入日报不能用于对外披露，对外口径见年报"，这一句能避免很多误用。
第三项必须由业务决策人签字，而不是技术团队"选一个看起来对的"。技术能说明差异来源与影响，但"哪个口径算官方"是业务决定。
// 口径文档的最小形态：可版本化、可追溯
metric: revenue_daily
version: 3
owner: finance-bi # 业务决策人
defined_at: 2026-11-10
changes:
- v2: 排除测试账号（2026-09）
- v3: 退款按发生日冲减（2026-11）
consumers: # 谁在用，改口径要通知谁
- finance-report
- ops-dashboard
consumers 这一栏决定了改口径的成本：改一个定义会同时影响多个报表，没有这份清单就只能靠人记。
5. 长期机制：每日差额
| 机制 | 作用 |
|---|---|
| 每日自动对账 | 差额当天暴露，不积累 |
| 差额阈值告警 | 超过阈值通知双方 |
| 差额归因记录 | 形成"已知差异"清单 |
| 口径变更流程 | 避免静默改定义 |
第二项的阈值应设"能容忍的口径差 + 一点余量"，而不是 0。设 0 会天天告警，因为已知的口径差本来就存在。
// 每日对账的最小实现：比两个数，超阈值告警
A=$(psql -tAc "select revenue_a('2026-11-09')")
B=$(psql -tAc "select revenue_b('2026-11-09')")
diff=$(( A - B )); base=$(( A > 0 ? A : 1 ))
pct=$(( diff * 1000 / base )) # 千分比，避免浮点
[ ${pct#-} -gt 30 ] && echo "差额 ${pct}‰ 超阈值" && exit 1
exit 0
6. 排错：五种"对不上但查不出"
| 现象 | 成因 | 处理方向 |
|---|---|---|
| 差额稳定不变 | 口径不同 | 先对定义 |
| 差额随天数累积 | 边界处理不同 | 查跨期规则 |
| 差额正负交替 | 去重规则不同 | 查重复记录 |
| 某天突然大额差额 | 一次性数据修正 | 查变更记录 |
| 抽样对得上但总数不对 | 缺失或截断 | 查记录数与空值 |
定位这类问题有个直接办法：比两侧的记录数。总数差但抽样对，通常是"该有的记录没被算进去"，先对齐行数比对齐金额快得多。
-- 先对行数，再对金额：行数差说明过滤条件不同
SELECT (SELECT COUNT(*) FROM paid WHERE paid_at::date = '2026-11-09') AS a,
(SELECT COUNT(*) FROM revenue_src WHERE dt = '2026-11-09') AS b;
-- 行数一致而金额不同 → 计算过程问题；行数不同 → 过滤与边界问题
第五项很典型：抽样都是对的，说明单条计算没问题，问题在"该有的记录有没有都被算进去"——通常是过滤条件、分页截断、或时区边界。
7. 边界：什么情况不必正式仲裁
| 场景 | 为什么 | 做法 |
|---|---|---|
| 内部探索性报表 | 无对外承诺 | 标注"参考值" |
| 两套口径服务不同用途 | 本就该不同 | 明确标注用途 |
| 差异小于测量误差 | 无实际意义 | 设定容忍阈值 |
| 一次性分析 | 用完即弃 | 口头对齐即可 |
最后一条与流程有关：口径变更要像接口变更一样对待。它有版本号、有影响范围、有通知对象、有过渡期；把它当成"改个 SQL"，就会在某天发现某个下游报表悄悄变了数。
判断口径一句话：这两个数字会不会被拿去和第三方对账。会，必须有唯一口径与文档；不会，标注清楚就够了。
8. 自测
- 三个层次的对不上分别有什么特征？为什么排查顺序必须是定义、过程、数据？
- "收入"为什么能被定义在四个不同的时点上？对账第一步该问什么？
- 为什么"强行对齐差额"会让两边都失去可信度？正确做法是什么？
- 口径仲裁为什么必须由业务决策人签字而不是技术团队？
consumers这一栏解决了什么成本？每日差额的阈值为什么不该设 0？- "抽样都对、总数不对"通常指向哪三类原因？