发生了什么

商户每个月会拿到一张月账单:上面是当月汇总金额,下面是一笔笔订单的结算明细,每行写明是哪笔订单、这个月结算多少、分润多少。商户下载这份明细,逐笔核对分润有没有算错。

这些明细不是商户系统自己算出来的。每笔交易完成后,记录“这笔该结算多少钱”的是清结算系统;商户侧的账单程序按账单周期调用清结算的明细查询接口,把返回的每一行存进自己的明细表。商户在小程序里导出时,程序从这张表取出明细,配上账单的汇总金额,生成文件。也就是说,商户看到的明细是清结算数据的一份副本:取的时候少几行,副本里就少几行,而副本本身没有办法知道自己少了。

4 月的账单出来后,商户把导出的明细和另一套分润账单逐笔比对,发现少了两千多条。抽查其中一笔订单:它在清结算系统里查得到,在导出的明细里没有,商户侧明细表里也确实不存在这一行。账单上的汇总金额,和明细逐笔相加的结果对不上。同一账单周期里,还有其他商户的明细同样不全。

本质

这套流程里有两道“判断它齐不齐”的关卡,这次两道都用错了依据。

  1. 取数时,账单程序按页向清结算要明细,拿回来就落库,落完不核对这一批是否覆盖了这一账单期的全部订单。接口这次返回的行本身就少了一部分,落库的明细跟着少。
  2. 导出时,程序把库里的行原样写进文件,再填上账单的汇总金额,中间不比对两者是否吻合。少行不报错,金额对不上也不提示,文件照常可以下载。
  3. 事后另有一套补数任务,专门给不完整的账单补数据,但它的判断只认两种场景:这一账单期一条明细都没有,或者已有明细里有必填字段为空。
  4. 这次的账单两个条件都不满足:明细行在、字段也齐,只是比应得的少。任务走到判断就跳过,缺的两千多条一直留在缺失状态。
  5. 于是这份账单长期“看起来正常”——能导出、有金额、有明细,只是少了一截,只有商户拿另一套账单逐笔比才暴露出来。

“有明细”不等于“明细齐全”:完整性判断写成“有没有记录”,漏掉的恰好是“有记录但条数不够”这一类,也是最难被发现的一类。

查询接口为什么会少返回,属于清结算侧的问题,现在只确认了结果:同一笔订单在清结算查得到,商户侧明细表里却没有这一行。修复方向是把补数判断从“有没有”改成“够不够”——按账单周期把清结算的明细分页取全,用订单这类唯一业务键与本地做差集,缺一条补一条;补完再用明细金额合计与账单汇总金额对一次,不等就告警;导出前也加同一道核对,不通过就不生成文件。存量缺失的账单已经排期补数,尚未完成;接口本身的优化在推动清结算侧处理。修复是否上线、补数是否跑完并复核,现有信息里没有说明。

错误代码

// 补数任务:按商户与账单周期,判断这份账单要不要重新拉明细
public void repairBillDetails(String merchantNo, String period) {
    List<BillDetail> stored = detailMapper.listByPeriod(merchantNo, period);

    // 为什么错:只把“一条明细都没有”当成不完整
    if (stored.isEmpty()) {
        pullAllDetails(merchantNo, period);
        return;
    }
    for (BillDetail d : stored) {
        // 为什么错:只看已有行的字段全不全,不看行数够不够
        if (d.getOrderNo() == null || d.getFeeAmount() == null) {
            pullAllDetails(merchantNo, period);
            return;
        }
    }
    // 为什么错:走到这里就认定账单已完整,缺掉的那部分永远不会被补
    log.info("bill detail ok, merchant={}, period={}", merchantNo, period);
}

修复代码示例

// 修复:判据从“有没有明细”换成“与总账对不对得上”
public void repairBillDetails(String merchantNo, String period) {
    // 按页取到没有下一页为止,得到这一期应该有的全部明细
    List<BillDetail> expected = clearingClient.listAllDetails(merchantNo, period);
    Set<String> storedKeys = detailMapper.listKeysByPeriod(merchantNo, period);

    // 以订单号为唯一业务键做差集,缺一条补一条,而不是整份重来
    List<BillDetail> missing = expected.stream()
            .filter(d -> !storedKeys.contains(d.getOrderNo()))
            .collect(Collectors.toList());
    if (!missing.isEmpty()) {
        detailMapper.insertBatch(missing);
    }

    // 上游自己也会少返:补完再用金额总计核一次,差额必须报出来
    BigDecimal detailSum = detailMapper.sumAmount(merchantNo, period);
    if (detailSum.compareTo(billMapper.getSummaryAmount(merchantNo, period)) != 0) {
        alarm.warn("bill detail amount mismatch, merchant={}, period={}, filled={}",
                merchantNo, period, missing.size());
    }
}

两段代码改的是同一个判断:把“存在性”换成“与总账比对后的差额”。代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现;接口、表、字段与告警键的名字均为示意。

下次遇到这些场景要警惕

  • 给账单、对账这类数据副本写同步或补数任务时:先列出“完整”的判定依据,凡是只判断“有没有记录”“字段空不空”的,补上条数与金额校验;再拿一份故意少几行的账单跑一遍,确认任务会去补,而不是跳过。
  • 明细来自按页查询的接口时:取完核对本次返回条数与总笔数、上次条数,变少就告警。接口不报错不代表数据全,少返回是最安静的一种故障。
  • 对外导出账单或对账单之前:用明细合计与汇总金额对一次,不相等就不生成文件并通知到人;只把库里的行原样吐出去,等于把取数环节的缺失直接交给商户。
  • 排查“金额对不上”时:先比条数再比金额,按“上游返回—本地落库—导出文件”三段逐段核对,确定缺失发生在哪一层,不要一上来只查导出逻辑。