发生了什么

网点是线下租场地经营的场所,一个网点签一份租赁合同,合同上写明房东是谁、租金和电费按什么周期付给谁。系统按天给网点生成电费账单,账单上除了金额,还要记两个主体:这笔费用对应的房东,以及实际收钱的收款方。账单生成后按收款方打款,所以这两个主体写错,钱就会付给不是合同约定的一方。

合同的关键内容不直接参与出账,而是另存一份,业务上叫合同快照:签约时把合同编号、房东、收款方、起止时间这些字段复制成一条独立记录。网点档案上还记着一个快照编号,指向“当前生效的那份合同快照”。生成电费账单时,程序不读合同本身,而是按这个编号找到快照,再从快照里取房东和收款方。

正常流程是:网点换房东或重签合同,新合同签完进入履约中,系统为新合同生成一份快照,然后把网点档案上的编号改成新快照的编号;此后的账单按新编号取数,房东和收款方就是新合同的。被替换的旧合同同时收尾。

这次网点在 3 月底把房东主体从原来的个人换成了另一家公司,新合同签好并进入履约中,旧合同已履行。到 5 月,这个网点的电费账单上,房东和收款方仍然是旧合同的那两个主体。账单照常生成,金额和账期没有异常,只是主体取错了。涉及几张账单、金额多少、是否已经打款,记录没有说明。

处置上,记录说已经让“租金清算账单生成不成功”不再中断合同流程,存量数据会统一处理;处理结果没有说明。

本质

重签生效时,系统要在同一段流程里做几件事:先按旧合同出一张租金清算账单,把重签之前没结清的租金单独结掉;再为新合同生成快照;最后把新快照的编号写回网点档案。最后一步是整件事的关键,因为下游的电费账单只认网点档案上的这个编号。

问题出在步骤顺序和失败处理上。

  1. 流程先执行生成租金清算账单这一步。这一次它没有生成账单,并且让整段流程中断了。至于账单为什么没生成,记录没有说明,能确认的是它失败后把后面的步骤一起带停。
  2. 中断发生在前,写回新快照编号的那条更新根本没有执行。新合同和它的快照都在库里,但网点档案上的编号仍然指向上一个合同的快照。
  3. 之后每天生成电费账单,程序读到网点档案上的旧编号,取到的是旧合同的快照,于是把旧合同的房东和收款方写进账单。
  4. 中断之后没有任何补偿:没有重试写回,也没有在出账前核对“档案上的快照是不是这个网点最新履约中合同的快照”。所以错误一路保留到 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 记录待补任务。示例假设档案编号的回写与清算账单生成可以分开提交,真实实现需要按项目的事务边界确认;清算失败后的补跑逻辑不在示例内。

下次遇到这些场景要警惕

  • 合同换了房东或收款主体并重签:先核对网点档案上的快照编号是否等于新合同的快照编号,再抽一张重签后新生成的账单,看房东和收款方是不是新主体。只看合同状态是“履约中”不够。
  • 一个流程里既有生成单据、又有回写关键字段:构造前置单据生成失败的场景,观察关键回写是否仍然执行、失败是否留痕可补。回写排在失败步骤之后又没捕获异常时,错误会静默发生。
  • 下游只按档案上的编号取主体、金额等信息:在取数处校验编号对应的版本是否为最新履约中合同的快照,不一致就不出单并告警,不能照旧取上一版。
  • 这类修复上线之后:除了确认不再产生新错账单,还要按发生过主体变更的网点逐条核对已生成的账单,确认主体和打款状态,订正或作废后再补生成。