发生了什么
门店在原有合作基础上追加条款时,要在门店后台发起一份“补充协议”审批。审批通过后,签约服务会收到通过事件,用配置中心里的合同模板编号调用合同系统,创建一份补充协议合同。合同创建成功后才进入签署,进度表显示“待签署”或“签署中”,业务可以继续操作。
这一次,同一批 4 个门店在几分钟内先后走完审批流程,审批记录都显示已通过,审批节点和审批人也相同。但门店后台的进度表一直显示“审批中”,业务方点不动,以为审批没有通过。
排查确认:审批流程本身没有问题,审批实例状态已经是“已通过”;签约服务调用合同系统创建合同时,对方返回业务错误,提示请求里的合同分类不在该模板允许的范围内。签约服务连续重试了七八次,每次都失败,最后把合同记录标记为删除。进度表查不到有效合同,只能继续展示“审批中”。次日凌晨的对账任务把合同状态改成“已过期/审批驳回”,按钮才重新出现;但这只是把展示状态修正了,配置不修,业务再发起补充协议仍会在同一步失败。
本质
问题出在两侧配置没有对齐,而不是审批数据丢失或网络抖动。
- 审批流程结束时,流程实例状态已经是“已通过”,并发出审批通过事件。
- 签约服务收到事件后,从配置中心读取“补充协议”使用的合同模板编号,再按合同类型、资产属性、业务分类三个字段组装创建请求。
- 合同系统不只认模板编号,还会检查这个模板的合同分类白名单。请求里的三字段组合不在白名单内,合同系统返回业务错误码 1000,明确拒绝创建。
- 签约服务把这个业务拒绝当成可重试异常,重试七八次。每次只更换请求里的来源编码后缀,被拒绝的合同分类组合没有变化,所以每次结果都一样,反而放大了对合同系统的无效调用。
- 重试到上限后,签约服务把合同记录软删。软删只是标记删除,记录还在表里,但业务查询不再返回它。
- 进度表依赖签约服务保存的最新合同状态。合同记录被软删后,这个状态没有机会推进,前端又把“审批中”和“合同审批中”两种状态显示成同一个词,业务看到的就一直是“审批中”。
根因可以落到一句话:签约服务配置的模板编号,指向了一个不允许当前合同分类组合的模板;模板白名单在合同系统侧维护,签约服务侧只在调用时才知道结果,两侧没有发布前校验,也没有定期对账。
修复方向是先把模板编号改成允许该分类组合的模板,或由合同系统把该组合加回白名单;同时在创建前做模板能力校验,业务拒绝不重试并立即回滚状态、发出告警。修复上线状态待确认。
错误代码
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;
}
}
下次遇到这些场景要警惕
- 新增或修改合同模板编号时,先把该模板在合同系统里的合同分类白名单调出来,逐项核对请求会带的三个字段;再用一条真实业务数据在预发环境实际调用创建接口,观察返回码,不要只看配置中心保存成功。
- 审批流程通过后,完整走一遍“发起补充协议—审批通过—查合同记录—看进度表”的链路。断言合同记录存在且状态推进到待签署,而不是只断言审批实例已通过。
- 给跨系统调用加重试前,先区分业务拒绝和临时失败。构造一个合同分类不匹配的请求,确认程序不会反复重试、不会软删记录,并且能立即回滚进度、发出告警。
- 对账或补偿任务修好展示状态后,不要当成问题已解决。按合同类型和时间排查被软删的记录,确认影响范围;配置修复后重新发起一笔,验证合同真正创建成功。