发生了什么
平台对外要付的钱,是按结算单结的。一段时间内的应收应付算清后,系统生成一张结算单,单子上写着这笔钱是多少、付给谁。结算单本身不是最终付款依据,它要再推给下游的付款程序,由付款程序生成付款单,财务按付款单打款。正常链条是:结算单金额为正,推送下游成功,付款单生成,按期付款。
结算单有两条写入路径:一条是平台自己把待结算的账目合成一张结算单,下面称自捏合路径;另一条是清结算系统把算好的结算单同步过来。两条路径最终都写进同一张结算单表,也都要走推送下游这一步。
这次的问题是,一张结算单的含手续费金额是负数,推到下游时失败,付款单没有建出来,这笔结算就停在结算单这一步,走不到付款。
两条路径对金额的检查却不一样:自捏合路径判断了金额是否小于 0,同步路径完全没有判断。而自捏合路径判断的是不含税金额,真正推给下游的含手续费金额没有被判断。于是含手续费金额为负的单据,同步路径直接放行;自捏合路径只要不含税金额不为负,也照样放行。
本质
结算单上不止一个金额字段:一个是不含税金额,一个是含手续费的金额,后者才是下游付款单使用的金额口径。这两个字段各自存值,不含税金额为正,推不出含手续费金额也为正。
校验被写成了某条路径上的一个 if,而不是所有写入结算单的地方都必须经过的关卡;并且校验的字段还不是下游真正消费的那个。具体是两个缺口:
- 同步路径没有校验。清结算同步进来的结算单,程序直接落库并推送,负的含手续费金额在这里没有任何拦截。
- 自捏合路径的校验看错了字段。这条路径只比较不含税金额是否小于 0,含手续费金额不参与判断。不含税金额通过后,含手续费金额可以是负数,单据照样落库、照样推送。
于是一个负数金额一路走到下游。付款程序收到一张金额为负的付款请求,付款单建不出来,推送失败。同一条“结算金额必须为正”的约束,被实现成了某个入口的局部检查,而真正被下游使用的字段始终没被检查。
修复方向是把金额校验收敛成结算单落库前的唯一出口,或者让两条路径调用同一个校验方法;校验对象改成下游真正使用的含手续费金额,其他金额字段一并判断;校验不通过就拒绝写入、拒绝推送,错误信息带上能定位到该笔结算的标识。已经产生的负数结算单要单独筛出来修正,只改校验不会让存量单据自动恢复。这次的处置是转成产品需求排期优化,代码是否按这个方向改过、是否上线,尚待确认。
下面的代码是按上述机制写的 Java 教学示例,用来对比“各路径各写各的校验”和“统一出口校验”,不代表实际项目源码或已上线实现。
错误代码
// 教学示例:两条生成路径,一条只查不含税金额,一条完全不查
public class SettlementBillService {
private final SettlementBillRepository repository;
private final PaymentOrderClient paymentOrderClient;
// 路径一:平台自行捏合生成
public void createByMerge(SettlementBill bill) {
// 为什么错:只校验不含税金额,含手续费金额不参与判断,
// 不含税为正、含手续费为负时照样放行
if (bill.getAmountExcludingTax().compareTo(BigDecimal.ZERO) < 0) {
throw new BizException("不含税金额不能为负");
}
repository.save(bill);
paymentOrderClient.push(bill); // 下游用的是含手续费金额
}
// 路径二:清结算同步进来
public void createFromSync(SettlementBill bill) {
// 为什么错:这条路径没有任何金额校验,负数直接落库并推送
repository.save(bill);
paymentOrderClient.push(bill);
}
}
修复代码示例
// 教学示例:两条路径共用同一个校验出口,并校验下游真正使用的字段
public class SettlementBillService {
private final SettlementBillRepository repository;
private final PaymentOrderClient paymentOrderClient;
public void createByMerge(SettlementBill bill) { saveAndPush(bill); }
// 同步入口不再绕过校验
public void createFromSync(SettlementBill bill) { saveAndPush(bill); }
private void saveAndPush(SettlementBill bill) {
// 下游付款单按含手续费金额扣款,这里必须校验它
requireNotNegative(bill.getAmountWithFee(), "含手续费金额");
requireNotNegative(bill.getAmountExcludingTax(), "不含税金额");
repository.save(bill);
paymentOrderClient.push(bill);
}
private void requireNotNegative(BigDecimal amount, String name) {
if (amount.compareTo(BigDecimal.ZERO) < 0) {
throw new BizException(name + "不能为负,结算单未生成");
}
}
}
下次遇到这些场景要警惕
- 给结算单这类“一张单决定后续付款”的数据加校验时:先把所有能写入它的入口列全,包括页面操作、定时任务、外部系统同步、补数据脚本,逐个确认是否经过同一处校验;只加在其中一个入口,等于没有加。
- 校验金额前:先确认下游或财务实际按哪个字段收付,就校验哪个字段,不要只校验中间结果(例如不含税金额);把单据上对外的每个金额字段都判一遍,避免“这个字段过了、那个字段是负的”。
- 推送下游之前:在发送侧做一次断言,金额为正、必填项齐全;下游的拒收只能作为最后兜底,不能把金额合法性的责任留给对方。
- 改完校验做回归时:按每条入口各造一条负数金额的数据,确认都被拦住且没有生成结算单;同时扫一遍存量数据里已经存在的负数单据,确认它们是修正还是重推。