发生了什么

网点是平台在线下开的经营点位,租场地放设备、对外营业。每个网点都要和场地方签租赁合同,合同写明租期起止;快到期时要续签,续签不是给原合同延期,而是重新发起一份新合同,再走一遍审批和电子签署。

每份合同在内部合同系统有一条记录,状态大致分审批中、已签署、已取消。同一个网点同时只允许有一份还在流程中的合同,所以发起新合同前会做重复合同校验:查到一条处于进行中状态的合同,就不允许再发起。网点档案上另有一个「最新合同状态」,由合同记录同步过来,页面靠它显示网点是已签约还是签约中。

正常流程是:内部先建记录,再把合同推送到外部电子签约平台创建,双方签完后平台回写已签署,合同记录和网点状态一起变成已签约。外部创建失败时,本地记录应改成失败或取消,网点状态回到上一份有效合同。

这次的问题出在一条 2023 年 6 月发起的变更协议上。该网点当时有一份正式租赁合同已签署生效,有效期到 2026 年 6 月 11 日;2023 年 6 月 21 日,又有人为它发起过一条变更协议。内部系统为这条协议留下了记录,状态停在审批中;但拿记录编号到外部签约平台查,查不到任何数据,这份协议在外部从未真正创建成功。此后近三年,没人处理这条记录。

2026 年 6 月初,正式合同临近到期,运营发起续签。重复合同校验读到这条审批中的记录,认定该网点已有一份进行中的合同,拒绝发起;网点档案上的最新合同状态也早被它带成了审批中,页面显示签约中。网点明明有一份仍在有效期内的正式合同,却发不出续签。

这次确认的影响是续签被拦,需要人工订正数据才恢复。外部创建为什么没有成功、还有没有别的网点卡在同类记录上,材料里没有依据。

本质

一句话:内部先落了一条审批中的合同记录,外部平台却始终没有这份协议,中间没有步骤把这条记录收尾;它作为一条永远不结束的在途合同,三年后把续签拦下了。

  1. 发起时先写本地记录。内部建记录并置为审批中,同时把网点档案上的最新合同状态也改成审批中。正常流程里这只是开始,要等外部创建成功、双方签完,状态才会走到终点。
  2. 外部创建没有成功。按同一条记录的编号去外部平台查,没有任何数据,这条记录对应的协议在外部根本不存在。
  3. 没人给本地记录收尾。外部没建成之后,本地没有把记录改成失败或取消,也没有任务核对“本地停在审批中的记录,在外部是否真的存在”。它停在审批中,一停近三年。
  4. 记录一直参与业务判断。重复合同校验把进行中状态集合里的记录都当成有效在途合同;网点最新合同状态也被它带着。两处都认为这个网点正在签合同。
  5. 续签因此被拦。真正有效的正式合同还在有效期内,但校验只看本地状态,既不确认外部有没有这份协议,也不看记录停了多久。

这次的处理是按单条数据订正:把那条记录从审批中改为已取消,把网点最新合同状态改回已签约,正式合同仍在有效期内。同类问题已记改进项,代码层修复的上线状态待确认。

这里的关键区别是:这条记录不是“外部签了一半”,而是外部压根没有这份协议;状态看起来在进行中,实际没有任何流程在推进。

修复方向是:本地记录只有在外部创建成功后才进入在途状态,创建失败立即置为失败或取消;对账任务定期扫描长期停在非终态的记录,回查外部是否存在对应单据,不存在就作废并把网点状态回退到有效合同;重复合同校验不要只看本地状态集合,至少同时确认外部存在对应合同、或该合同仍在有效期内。

错误代码

class ContractCreateService {
    void createAmendment(long nodeId, AmendmentForm form) {
        ContractRecord record = new ContractRecord();
        record.setNodeId(nodeId);
        // 为什么错:外部还没创建,就先把“审批中”写进本地并同步到网点
        record.setStatus("CONTRACT_APPROVING");
        contractMapper.insert(record);
        nodeMapper.updateLatestContractStatus(nodeId, "CONTRACT_APPROVING");
        try {
            signClient.create(buildRequest(record, form));
        } catch (Exception e) {
            // 为什么错:只记一行日志,本地记录仍是审批中,没有收尾
            log.error("create agreement failed, id={}", record.getId(), e);
        }
    }
}
class ContractCheckService {
    boolean hasRunningContract(long nodeId) {
        // 为什么错:只按本地状态集合判断在途,不确认外部是否真有这份合同
        return contractMapper.countByNodeAndStatusIn(nodeId, RUNNING_STATUS) > 0;
    }
}

修复代码示例

class ContractCreateService {
    void createAmendment(long nodeId, AmendmentForm form) {
        ContractRecord record = new ContractRecord();
        record.setStatus("PENDING_CREATE");      // 先落待创建态,还不算在途
        contractMapper.insert(record);
        try {
            record.setRemoteNo(signClient.create(buildRequest(record, form)));
            record.setStatus("CONTRACT_APPROVING");  // 外部建成后才进入在途
            contractMapper.update(record);
            nodeMapper.updateLatestContractStatus(nodeId, "CONTRACT_APPROVING");
        } catch (Exception e) {
            record.setStatus("FAILED");          // 失败当场收尾,不留悬空记录
            contractMapper.update(record);
        }
    }
}
class ContractReconcileJob {
    void reconcile() {
        // 扫描长期停在非终态的记录,外部查无此单就作废
        contractMapper.selectStaleNonFinal().stream()
            .filter(r -> !signClient.exists(r.getRemoteNo()))
            .forEach(r -> {
                r.setStatus("CANCEL");
                contractMapper.update(r);
                nodeMapper.resetLatestToValidContract(r.getNodeId());
            });
    }
}

上面的改法是从原因推导的方向,未实施也未验证。代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现;类名、方法名与状态常量均为示意。

下次遇到这些场景要警惕

  • 设计“内部记录加外部平台”两步创建的流程时:先写下本地每个状态代表什么,确认哪个才代表外部已建成;再用“外部创建失败”走一遍,看会不会留下一条永远不结束的记录。
  • 增加或修改“进行中”状态集合时:先找出还有哪些判断在读它,例如重复校验、入口按钮、列表筛选;再拿一条外部不存在、本地停在非终态的历史记录,验证它不会拦住新业务。
  • 给网点、订单这类主数据加“最新状态”汇总字段时:确认这个值由哪条记录回写、多条记录并存时取的是哪一条;用一条孤儿历史记录验证页面显示是否与当前有效合同一致。
  • 上线对账或清理任务时:明确扫描条件是否覆盖长期没有更新的记录,并核对任务产出的异常清单有没有人跟进;只告警不订正,孤儿记录仍然会留在业务判断里。