发生了什么

平台和商户的租金是这样结的:每个网点按期产生一笔租金账单,账单上记录应付金额和结算状态;状态是“待结算”,表示这笔钱还没有付给商户。待结算账单会按批次归到一张结算单下,交给结算平台统一打款。结算平台打款完成后,结算服务要把“结算完成”这个结果通知账单侧;账单侧收到通知,才会把租金账单改成“已结算”,并把结算平台返回的结算单号写到账单上。商户在后台看到账单已结算,也能顺着这个号码找到对应的结算单。

正常结果是两边对得上:结算单显示结算完成,它下面的租金账单也显示已结算,账单上带着平台结算单号。

这次反馈的是同一家商户名下 4 个网点的 4 笔租金账单,合计 6300 元。这 4 笔账单在后台仍是“待结算”,账单上的平台结算单号是空的,商家点进账单找不到对应的结算单。但结算侧的数据显示,对应的结算单在 4 月初就已经是结算完成,结算侧自己的账单也记着平台结算单号。也就是说,钱在结算平台那边已经结掉了,账单侧却不知道。

后来对这 4 笔账单逐条补发了结算成功通知,账单状态和平台结算单号都正常回填了。这反过来证明账单侧收到通知后的处理没有问题,断点在通知本身没有发出来。

本质

一句话:结算单进入“结算完成”之后,本该发给账单侧的结算成功通知被跳过了,账单侧没有消息可处理,只能一直停在待结算。

  1. 这批账单的结算结果是从结算平台回传后同步到结算侧的:结算单被写成结算完成,结算侧账单记上平台结算单号。这一步只改了状态,通知要靠另外的动作发出。
  2. 负责收尾的结算完成入口一进来先做幂等判断:如果结算单已经是结算完成,就直接返回。这个判断原本是为了防止同一张结算单被重复处理。
  3. 但返回点在“发结算成功通知”之前。对结算单来说,返回是对的——状态已经是完成,不需要再改;对账单侧来说,这条通知就跟着没了。
  4. 系统里还有第二条能发这条通知的路径,是从结算平台回传结果同步过来的消费程序;它发通知的那一段受一个配置开关控制,开关不开启就不往下发。开关在事发时是什么取值,没有确认结果。
  5. 这一次,两条路径都没有把通知发出去。账单侧收不到消息,租金账单保持待结算、平台结算单号为空。
  6. 补发通知后 4 笔账单全部更新成功,说明接收和更新环节正常,缺口只在“通知有没有发出去”这一段。

幂等判断应该只挡住重复的状态变更,不能把“要通知下游”这件事一起挡掉。

根子在职责边界:状态判断和通知发送写在同一个入口里,共用同一个提前返回。通知是“结算完成”这个事实对外产生的影响,只要事实成立,通知就应该有且只有一次;用“状态是不是刚刚发生变化”来决定“要不要发通知”,凡是进入收尾入口时结算单已经算完成的单据,通知都会被跳过。备用入口再挂一个开关,等于把唯一的兜底交给配置状态。

修复方向是:把通知从事务内的状态判断里拆出来,按结算单号落一条结算完成事件,用唯一键保证同一张结算单只有一条事件,由独立的发件程序负责重试投递;账单侧按账单编号做幂等,重复收到也只更新一次。开关只用于灰度新逻辑,不作为唯一通知路径的开关。这套改法是否已经长期落地,尚未确认。

错误代码

public class SettlementBillInnerServiceImpl {

    public void finishSettlementStatus(SettlementBill bill) {
        // 为什么错:幂等判断放在方法入口,结算单已是终态就直接返回,
        // 后面“通知账单侧”的步骤被一起跳过,账单永远收不到这条消息
        if (bill.getStatus() == SettlementStatus.SETTLED) return;
        bill.setStatus(SettlementStatus.SETTLED);
        settlementBillMapper.updateById(bill);
        // 通知写在 return 之后:进方法时状态已算完成,这行就不会执行
        mqProducer.send(BILL_STL_TOPIC, "RENT_BILL",
                bill.getRentBillNo(), buildSettledMsg(bill));
    }
}

public class SettlementNoticeConsumer {

    public void process(SettleNotice notice) {
        // 为什么错:另一条能发同一条通知的入口整段被开关挡住,
        // 开关不开启时,主路径跳过后就没有任何路径补发
        if (!switchService.isOn("syncBillStlStatusMsgSwitch")) return;
        mqProducer.send(BILL_STL_TOPIC, "RENT_BILL",
                notice.getRentBillNo(), buildSettledMsg(notice));
    }
}

修复代码示例

public class SettlementBillInnerServiceImpl {

    @Transactional(rollbackFor = Exception.class)
    public void finishSettlementStatus(SettlementBill bill) {
        if (bill.getStatus() != SettlementStatus.SETTLED) {
            bill.setStatus(SettlementStatus.SETTLED);
            bill.setCompleteTime(new Date());
            settlementBillMapper.updateById(bill);
        }
        // 修复:通知不再由“状态是否刚变化”决定,而是按结算单号去重落一条事件;
        // 即使状态已被其他入口改成终态,这里仍会补齐缺失的待发事件
        outboxService.saveIfAbsent(EventType.STL_SETTLED, bill.getId(),
                BILL_STL_TOPIC, bill.getRentBillNo(), buildSettledMsg(bill));
    }
}
public class RentBillSettleConsumer {

    // 修复:账单侧按账单编号幂等,重复投递只更新一次
    public void onSettled(SettledMessage message) {
        if (rentBillMapper.isSettled(message.getRentBillNo())) {
            return;
        }
        rentBillMapper.markSettled(message.getRentBillNo(),
                message.getPlatformStlNo());
    }
}

代码是脱敏教学示例,用来说明错误与修复思路,不代表实际项目源码或已上线实现。主题名、方法名、事件类型均为示意;唯一键、发件程序的重试与积压处理需要按实际投递组件补齐。

下次遇到这些场景要警惕

  • 给状态变更入口加幂等判断时:先列出“状态变更成功后必须发生的对外动作”——通知、回写、占用额度,再检查提前返回是否把它们一起跳过;构造“结算单已被其他入口改成完成,再调用该入口”的场景,确认下游仍能收到通知。
  • 一条通知有多个发送入口时:把每个入口的触发条件和开关状态列成一张表,在开关关闭的条件下完整走一遍结算,观察下游是否还有消息到达;不要让一个开关成为唯一兜底。
  • 用“状态字段是否变化”决定发不发消息时:先确认下游需要的是“这一次变化”,还是“这件事已经发生”;用重复调用、跨入口调用各验一次,看下游是否都只得到一次通知。
  • 补发过历史通知后:除核对本次账单的状态、平台结算单号和结算单关联,还要扫一遍同期“结算侧已完成、账单侧仍待结算”的记录,确认没有漏补的账单。