发生了什么

门店在原有合作基础上追加条款时,要在门店后台发起一份“补充协议”审批。审批通过后,签约服务会收到通过事件,用配置中心里的合同模板编号调用合同系统,创建一份补充协议合同。合同创建成功后才进入签署,进度表显示“待签署”或“签署中”,业务可以继续操作。

这一次,同一批 4 个门店在几分钟内先后走完审批流程,审批记录都显示已通过,审批节点和审批人也相同。但门店后台的进度表一直显示“审批中”,业务方点不动,以为审批没有通过。

排查确认:审批流程本身没有问题,审批实例状态已经是“已通过”;签约服务调用合同系统创建合同时,对方返回业务错误,提示请求里的合同分类不在该模板允许的范围内。签约服务连续重试了七八次,每次都失败,最后把合同记录标记为删除。进度表查不到有效合同,只能继续展示“审批中”。次日凌晨的对账任务把合同状态改成“已过期/审批驳回”,按钮才重新出现;但这只是把展示状态修正了,配置不修,业务再发起补充协议仍会在同一步失败。

本质

问题出在两侧配置没有对齐,而不是审批数据丢失或网络抖动。

  1. 审批流程结束时,流程实例状态已经是“已通过”,并发出审批通过事件。
  2. 签约服务收到事件后,从配置中心读取“补充协议”使用的合同模板编号,再按合同类型、资产属性、业务分类三个字段组装创建请求。
  3. 合同系统不只认模板编号,还会检查这个模板的合同分类白名单。请求里的三字段组合不在白名单内,合同系统返回业务错误码 1000,明确拒绝创建。
  4. 签约服务把这个业务拒绝当成可重试异常,重试七八次。每次只更换请求里的来源编码后缀,被拒绝的合同分类组合没有变化,所以每次结果都一样,反而放大了对合同系统的无效调用。
  5. 重试到上限后,签约服务把合同记录软删。软删只是标记删除,记录还在表里,但业务查询不再返回它。
  6. 进度表依赖签约服务保存的最新合同状态。合同记录被软删后,这个状态没有机会推进,前端又把“审批中”和“合同审批中”两种状态显示成同一个词,业务看到的就一直是“审批中”。

根因可以落到一句话:签约服务配置的模板编号,指向了一个不允许当前合同分类组合的模板;模板白名单在合同系统侧维护,签约服务侧只在调用时才知道结果,两侧没有发布前校验,也没有定期对账。

修复方向是先把模板编号改成允许该分类组合的模板,或由合同系统把该组合加回白名单;同时在创建前做模板能力校验,业务拒绝不重试并立即回滚状态、发出告警。修复上线状态待确认。

错误代码

public void createSupplementContract(ApprovalEvent event) {
    String templateCode = config.get("contract.agreement.template-code");
    ContractCreateRequest request = new ContractCreateRequest();
    request.setTemplateCode(templateCode);
    request.setContractType("TYPE_SUPPLEMENT");   // 示意值
    request.setPropertyCode("PROPERTY_STANDARD"); // 示意值
    request.setBusinessClass("CLASS_STORE");      // 示意值
    for (int i = 0; i < 8; i++) {
        // 为什么错:只换来源编码后缀,被拒绝的合同分类组合没有变化
        request.setSourceCode(event.getSourceCode() + "-" + i);
        try {
            contractClient.create(request);
            return;
        } catch (BusinessException e) {
            // 为什么错:业务校验拒绝也当成可重试异常,继续打合同系统
            log.warn("create agreement contract failed, retry {}", i, e);
        }
    }
    // 为什么错:重试耗尽后软删记录,进度表再也查不到这份合同
    contractRecordMapper.softDelete(event.getContractId());
}

修复代码示例

public void createSupplementContract(ApprovalEvent event) {
    String templateCode = config.get("contract.agreement.template-code");
    ContractCategory category = ContractCategory.of(
            "TYPE_SUPPLEMENT", "PROPERTY_STANDARD", "CLASS_STORE"); // 示意值
    // 调用前先确认模板允许该分类组合,配置错误在入口就暴露
    if (!contractClient.templateAllows(templateCode, category)) {
        throw new ConfigMismatchException(templateCode + " 不允许 " + category);
    }
    ContractCreateRequest request = new ContractCreateRequest();
    request.setTemplateCode(templateCode);
    request.setCategory(category);
    request.setSourceCode(event.getSourceCode());
    try {
        contractClient.create(request);
    } catch (BusinessException e) {
        // 业务拒绝不重试:立即回滚进度、保留记录并告警
        contractRecordMapper.updateStatus(event.getContractId(), ContractStatus.CREATE_FAILED);
        merchantStatusMapper.updateLatestStatus(event.getMerchantId(), ContractStatus.EXPIRE);
        alert.warn("supplement contract rejected", templateCode, e.getCode());
        throw e;
    }
}

下次遇到这些场景要警惕

  • 新增或修改合同模板编号时,先把该模板在合同系统里的合同分类白名单调出来,逐项核对请求会带的三个字段;再用一条真实业务数据在预发环境实际调用创建接口,观察返回码,不要只看配置中心保存成功。
  • 审批流程通过后,完整走一遍“发起补充协议—审批通过—查合同记录—看进度表”的链路。断言合同记录存在且状态推进到待签署,而不是只断言审批实例已通过。
  • 给跨系统调用加重试前,先区分业务拒绝和临时失败。构造一个合同分类不匹配的请求,确认程序不会反复重试、不会软删记录,并且能立即回滚进度、发出告警。
  • 对账或补偿任务修好展示状态后,不要当成问题已解决。按合同类型和时间排查被软删的记录,确认影响范围;配置修复后重新发起一笔,验证合同真正创建成功。