发生了什么
网点是线下租场地经营的场所,一个网点签一份租赁合同,合同上写明房东是谁、租金和电费按什么周期付给谁。系统按天给网点生成电费账单,账单上除了金额,还要记两个主体:这笔费用对应的房东,以及实际收钱的收款方。账单生成后按收款方打款,所以这两个主体写错,钱就会付给不是合同约定的一方。
合同的关键内容不直接参与出账,而是另存一份,业务上叫合同快照:签约时把合同编号、房东、收款方、起止时间这些字段复制成一条独立记录。网点档案上还记着一个快照编号,指向“当前生效的那份合同快照”。生成电费账单时,程序不读合同本身,而是按这个编号找到快照,再从快照里取房东和收款方。
正常流程是:网点换房东或重签合同,新合同签完进入履约中,系统为新合同生成一份快照,然后把网点档案上的编号改成新快照的编号;此后的账单按新编号取数,房东和收款方就是新合同的。被替换的旧合同同时收尾。
这次网点在 3 月底把房东主体从原来的个人换成了另一家公司,新合同签好并进入履约中,旧合同已履行。到 5 月,这个网点的电费账单上,房东和收款方仍然是旧合同的那两个主体。账单照常生成,金额和账期没有异常,只是主体取错了。涉及几张账单、金额多少、是否已经打款,记录没有说明。
处置上,记录说已经让“租金清算账单生成不成功”不再中断合同流程,存量数据会统一处理;处理结果没有说明。
本质
重签生效时,系统要在同一段流程里做几件事:先按旧合同出一张租金清算账单,把重签之前没结清的租金单独结掉;再为新合同生成快照;最后把新快照的编号写回网点档案。最后一步是整件事的关键,因为下游的电费账单只认网点档案上的这个编号。
问题出在步骤顺序和失败处理上。
- 流程先执行生成租金清算账单这一步。这一次它没有生成账单,并且让整段流程中断了。至于账单为什么没生成,记录没有说明,能确认的是它失败后把后面的步骤一起带停。
- 中断发生在前,写回新快照编号的那条更新根本没有执行。新合同和它的快照都在库里,但网点档案上的编号仍然指向上一个合同的快照。
- 之后每天生成电费账单,程序读到网点档案上的旧编号,取到的是旧合同的快照,于是把旧合同的房东和收款方写进账单。
- 中断之后没有任何补偿:没有重试写回,也没有在出账前核对“档案上的快照是不是这个网点最新履约中合同的快照”。所以错误一路保留到 5 月的账单上才被发现。
把关键字段的回写排在可能失败的前置步骤之后,前面一出错,回写就被整体跳过,下游会一直按旧值出单。
修复方向是把两件事解耦:网点档案编号的回写不再依赖清算账单是否生成成功,清算失败单独留一条待补记录并告警;出账前再校验档案编号与最新履约中合同的快照是否一致,不一致就不出单或转人工核对。记录说已经优化成“清算账单生成不成功也不会中断合同流程”,具体实现和验证结果没有给出;已生成的存量账单需要人工订正。
下面两段 Java 是脱敏教学示例,用于对比“回写排在失败步骤之后”和“回写独立、失败留痕、出账前校验版本”,不代表实际项目源码或已上线实现。
错误代码
public class ContractResignSyncService {
/** 重签生效:结清旧合同未结租金,再把新快照登记到网点档案 */
public void onResignEffective(long outletId, Contract newContract) {
Contract old = contractMapper.selectPerforming(outletId);
Snapshot snapshot = snapshotMapper.insert(Snapshot.of(newContract));
// 为什么错:示例里清算账单生成失败以异常返回,方法直接退出,
// 后面的档案编号回写不会执行
rentClearingService.createFor(old, newContract.getEffectDate());
// 为什么错:回写排在可能失败的一步之后,一旦中断就永远不执行,
// 档案上的编号一直停留在上一份合同的快照
contractMapper.updateCurrentSnapshot(outletId, snapshot.getId());
}
/** 电费日账单:只按档案上的编号取快照,不判断取到的是哪一版 */
public Bill buildDailyElectricBill(long outletId, LocalDate day) {
ContractMain main = contractMapper.selectByOutlet(outletId);
Snapshot used = snapshotMapper.selectById(main.getCurrentSnapshotId());
// 为什么错:旧合同的房东和收款方被原样写进账单,照常生成、照常打款
return Bill.of(used.getLandlordId(), used.getPayeeId(), day);
}
}
修复代码示例
public class ContractResignSyncService {
public void onResignEffective(long outletId, Contract newContract) {
Contract old = contractMapper.selectPerforming(outletId);
Snapshot snapshot = snapshotMapper.insert(Snapshot.of(newContract));
// 修正:先回写档案编号并单独提交,下游取数不再依赖清算账单是否成功
contractMapper.updateCurrentSnapshot(outletId, snapshot.getId());
// 修正:清算失败只影响它自己,记一条待补并告警,不中断主流程
try {
rentClearingService.createFor(old, newContract.getEffectDate());
} catch (Exception e) {
clearingRetryMapper.enqueue(old.getId(), newContract.getEffectDate(), e.getMessage());
alarm.send("租金清算账单生成失败,待补", old.getId());
}
}
/** 修正:出账前校验档案编号必须等于最新履约中合同的快照 */
public Bill buildDailyElectricBill(long outletId, LocalDate day) {
ContractMain main = contractMapper.selectByOutlet(outletId);
Snapshot latest = snapshotMapper.selectByContract(main.getPerformingContractId());
if (!latest.getId().equals(main.getCurrentSnapshotId())) {
throw new IllegalStateException("合同快照版本不一致,转人工核对");
}
return Bill.of(latest.getLandlordId(), latest.getPayeeId(), day);
}
}
ContractMain 是网点档案(含当前履约合同编号和快照编号),Snapshot 是合同快照,rentClearingService 负责生成租金清算账单,clearingRetryMapper 记录待补任务。示例假设档案编号的回写与清算账单生成可以分开提交,真实实现需要按项目的事务边界确认;清算失败后的补跑逻辑不在示例内。
下次遇到这些场景要警惕
- 合同换了房东或收款主体并重签:先核对网点档案上的快照编号是否等于新合同的快照编号,再抽一张重签后新生成的账单,看房东和收款方是不是新主体。只看合同状态是“履约中”不够。
- 一个流程里既有生成单据、又有回写关键字段:构造前置单据生成失败的场景,观察关键回写是否仍然执行、失败是否留痕可补。回写排在失败步骤之后又没捕获异常时,错误会静默发生。
- 下游只按档案上的编号取主体、金额等信息:在取数处校验编号对应的版本是否为最新履约中合同的快照,不一致就不出单并告警,不能照旧取上一版。
- 这类修复上线之后:除了确认不再产生新错账单,还要按发生过主体变更的网点逐条核对已生成的账单,确认主体和打款状态,订正或作废后再补生成。