发生了什么

网点是平台在线下开的经营点位,系统里每个网点要挂一份合同,合同写明合作从哪天到哪天、结算归哪个商户。系统会把合同的关键内容另存一份,这份记录在业务里叫「合同快照」。合同记录和快照按同一个合同编号对应,一份合同正常情况下只应该有一条快照。

签约的正常顺序是:签约完成,系统先写入合同快照,再生成网点档案,网点随后进入待运营。商户想提前结束合作时走的是「提前退租」:先在后台提交退租申请,填好退租原因和期望结束日期,再走审批;审批通过之后,系统还要落地一串动作,包括按原合同生成一份退租快照、把网点的合作结束日期改成退租日期、把网点关闭。只有这些动作都执行完,网点才算真正退出。

这一次,2025-11-06 的签约只完成了前半段:系统写入了合同快照,但网点档案没有生成,后台只能一直显示「签约中」。2026-09-02 凌晨,系统为这份合同补生成了网点,网点才出现在后台。当天下午,有人对这个网点提交了提前退租,退租原因写的是「系统bug,9月2日自动生成」;一分钟左右审批通过,但审批通过之后的系统处理报错中断了。

结果是:网点状态仍是待运营,网点上的最新合同状态仍是「合同处理中」,后台页面据此显示「合同签署中」,关闭操作被拦下;对应的合同记录停在审批通过、处理中,既没有取消也没有完成;退租快照没有生成,网点的合作结束日期没有更新,网点也没有关闭。

本质

一句话:退租落地时要按合同编号取这份合同的快照,代码按「只会有一条」实现,实际取到两条就抛错,整段落地随之中断,审批通过之后没有一步执行。

  1. 签约那次只完成了一半。2025-11-06 签约写入了合同快照,却没有生成网点档案,网点侧没有记录可看,后台只能显示签约中。这是长期显示签约中的直接原因。
  2. 补生成只补了缺的那一半。2026-09-02 系统补生成了网点,解决的是「网点不存在」,合同侧的数据没有随之变化;这条合同编号下还有另一条快照,属于历史遗留的重复数据。
  3. 退租落地按唯一取数。提前退租要在原合同基础上生成退租快照,第一步就是按合同编号取原合同快照。读取方法假设这个编号只对应一条记录,命中两条时直接抛出异常。
  4. 异常中断了整段落地。异常发生在落地方法内部,处理随之中断,后面的生成退租快照、更新合作结束日期、关闭网点都没有执行;审批侧已经记成通过,业务侧没有任何变化。后台再读状态,读到的还是「合同处理中」,于是显示成「合同签署中」,关闭检查按流程未结束把操作拦下。
  5. 没有自动路径能把它补完。预退租这类记录本来不需要合同编号,每天的对账任务按设计会主动跳过它,所以状态不会自己恢复。
  6. 处置方向是先清掉去年遗留的那条重复快照,它对应的网点在系统里已经不存在;再让系统重跑这次提前退租,走完生成退租快照、更新合作结束日期、关闭网点;重跑不可行时,业务可以在后台重新提交一次提前退租,但必须先清掉重复快照,否则会再次中断。同时把「同一合同编号下多条快照」的存量数据统一排查处理。这些动作是否已经执行、修复是否上线,记录没有说明。

审批通过只代表审批环节结束;落地方法里一次本应唯一的读取拿到两条就抛错,整段落地连同后面的关闭动作一起被中断。

错误代码

public class EarlyTerminationService {

    /** 提前退租落地:取合同快照,生成退租快照并关闭网点 */
    @Transactional
    public void settle(TerminationApply apply) {
        // 为什么错:这个合同编号下实际有两条快照,按「只会有一条」取数,
        // 查询直接抛异常,方法中断,下面三步一步都没执行
        ContractSnapshot snapshot = snapshotMapper
                .selectOneByContractNo(apply.getContractNo());
        snapshotMapper.insert(snapshot.toExitSnapshot(apply.getEndDate()));
        outletMapper.updateCooperationEnd(apply.getOutletId(), apply.getEndDate());
        outletMapper.close(apply.getOutletId());        // 网点始终没有被关闭
        applyMapper.markFinished(apply.getId());
    }
}

修复代码示例

public class EarlyTerminationService {

    /** 修复方向:显式处理「一条、多条、没有」三种情况,落地失败留下可重试的记录 */
    @Transactional
    public void settle(TerminationApply apply) {
        List<ContractSnapshot> snapshots = snapshotMapper
                .listByContractNo(apply.getContractNo());
        if (snapshots.isEmpty()) {
            throw new BizException("合同快照不存在,需人工核对后再退租");
        }
        if (snapshots.size() > 1) {
            // 不再让异常打断落地:明确取创建时间最新的一条,并告警待人工清理
            log.warn("同一合同编号存在多条快照,contractNo={}, count={}",
                    apply.getContractNo(), snapshots.size());
        }
        ContractSnapshot snapshot = snapshots.stream()
                .max(Comparator.comparing(ContractSnapshot::getCreatedAt))
                .orElseThrow(() -> new BizException("合同快照不存在"));
        snapshotMapper.insert(snapshot.toExitSnapshot(apply.getEndDate()));
        outletMapper.updateCooperationEnd(apply.getOutletId(), apply.getEndDate());
        outletMapper.close(apply.getOutletId());
        applyMapper.markFinished(apply.getId());
    }
}

代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。读取侧兜底只能让这次落地跑完,按创建时间取最新一条只是示意,实际取哪一条要按业务规则确认;重复快照本身要按清单清理,新增写入也要有防重手段,顺序上先清存量再考虑约束。落地过程抛出的异常也不该只交给审批回调吞掉,失败要留下状态、告警并可重跑,否则审批侧和业务侧会长期对不上。

下次遇到这些场景要警惕

  • 看到按业务编号取单条记录的代码:先在该编号下统计实际条数,重点查历史迁移、补生成、重跑过的数据;只要可能不止一条,就显式处理多条并告警,别让异常直接打断主流程。
  • 做「补数据、补生成」的修复时:只补缺失的那一半不会清掉另一半的脏数据;补完要回查同一业务编号下的关联记录条数和状态,确认没有重复再继续后面的流程。
  • 审批通过后还要落地业务动作的流程:检查落地方法的异常有没有被接住、失败后审批侧与业务侧状态会不会长期分叉;用一条故意重复的关联数据构造落地失败,确认能看到失败原因并且可以重跑。
  • 依赖对账任务自愈的流程:确认对账取数会不会跳过这类记录,例如预退租本就不需要合同编号;被跳过的记录要另有人工或定时补偿入口。