发生了什么
网点要开店经营,得先和场地出租方签一份租赁合同:合同写清租哪块场地、合作期多长,签完之后网点按它履约、按周期结算。签合同由内部签约程序调用外部电子签约平台完成:平台建好合同并给出合同号,签约程序再把合同号和签署状态回写到本地合同记录。运营在签约管理后台看这些记录,判断网点有没有签好、能不能继续往下走。
正常顺序是:发起签约、平台建合同、回写合同号和状态。此后记录里的签署状态就是当前状态,后台按它展示。
这次的开头就和正常流程不一样。发起签约时,签约程序第一次调用平台的建合同接口就失败了,平台返回一个业务错误码,说明当前来源编码对应的数据不存在。程序按失败处理:在合同记录的扩展数据里写下错误提示“合同签约异常,请联系业务”,并标记为不能自助处理。
隔了一天,系统又发起了一次创建。这一次平台建合同成功,合同号回写到本地记录,状态变为已签署;主表的校验状态为通过,快照里这份合同处于履约中,平台侧也已归档。合同本身已经签署生效,合作期从签约当月起算一年。
但运营在后台看到的仍然是那句“合同签约异常,请联系业务”,来自扩展数据里前一天写下的错误记录。一次需求改动把这条错误提示读出来展示,方便运营看签约失败的原因,却没有考虑存量数据:早期失败、后来重试成功的合同,扩展数据里仍留着失败当时的错误信息。同时还发现,这个网点在网点表上的商户编号和名称为空,快照里有正确值,两处没有同步。
本质
一句话:后台把“最后一次失败时写下的错误信息”当成合同当前状态来展示,而重试成功的合同从来没有清掉这条错误信息。
-
合同记录里真正表示状态的是主表上的签署状态;扩展数据里的错误提示只是失败排查的线索,它在第一次调用失败时写入,此后不随合同状态变化自动更新。
-
系统后来重试时走的是“创建成功”分支:写合同号、改状态、回写快照,没有回头清理扩展数据里的错误提示,也没有复位“不能自助处理”的标记。同一份合同上于是同时存在两个相反结论:状态是已签署,错误提示仍是签约异常。
-
新的需求改动增加了“把错误提示展示到后台”的逻辑,读取时只看这个字段有没有值,不与主表状态对照。字段有值就显示异常,已经履约的合同也被报成异常。
-
存量数据放大了问题:这个字段过去只在失败时写入、成功后从不清理,历史上每次“先失败、后成功”的签约都留下残留,新逻辑上线后一次性全部显示成异常。
-
附带的那处不一致属于同一类问题:网点表的商户信息为空,快照里有值,同一份业务事实在两处数据源上不同步。它为什么没有写进去,目前还不清楚。
-
处置与修复方向。这次只做了状态确认:合同已签署生效,不需要处理;网点商户信息如有需要,走网点更新服务回填,兜底才直接改库。没有涉及代码改动,也没有说明是否需要上线修复,因此不能当作已经修好。修复方向是三件事:展示以主表签署状态为准,错误提示只在当前仍失败时才展示;成功回写时同步清空错误提示和“不可自助”标记;对存量做一次清理,把已签署却还带错误提示的记录刷掉。
错误提示存的是“上一次失败的错误信息”,不是当前状态;把它当状态读,已经履约的合同就会一直报签约异常。
错误代码
// 签约结果回写与后台展示(脱敏教学示例)
public void onSignResult(ContractRecord record, SignResult result) {
if (!result.isSuccess()) {
// 失败时把平台错误信息留在扩展字段里,供运营排查
record.setErrorMsg("合同签约异常,请联系业务");
record.setSelfServiceable(false);
contractMapper.updateError(record);
return;
}
// 重试成功:只把合同状态推进到已签署
// 为什么错:成功后没有清掉上一次失败写入的错误信息
record.setContractStatus(SIGNED);
record.setContractNo(result.getContractNo());
contractMapper.updateStatus(record);
}
// 后台详情:只要扩展字段有值就当作签约异常
public String displayMsg(ContractRecord record) {
// 为什么错:把“上一次失败的错误信息”当成当前状态读,不与主表状态对照
if (StringUtils.isNotBlank(record.getErrorMsg())) {
return record.getErrorMsg();
}
return statusText(record.getContractStatus());
}
修复代码示例
// 修复:成功回写时清理错误信息,展示以合同状态为准(脱敏教学示例)
public void onSignResult(ContractRecord record, SignResult result) {
if (!result.isSuccess()) {
record.setErrorMsg("合同签约异常,请联系业务");
record.setSelfServiceable(false);
contractMapper.updateError(record);
return;
}
record.setContractStatus(SIGNED);
record.setContractNo(result.getContractNo());
// 修复:成功就清掉历史错误提示,这个字段只代表当前一次的结果
record.setErrorMsg(null);
record.setSelfServiceable(true);
contractMapper.updateStatusAndClearError(record);
}
// 后台详情:先看主表状态,只有当前仍在失败态才展示错误信息
public String displayMsg(ContractRecord record) {
// 修复:错误提示只对“当前仍失败”的记录生效
if (record.isFailed() && StringUtils.isNotBlank(record.getErrorMsg())) {
return record.getErrorMsg();
}
return statusText(record.getContractStatus());
}
// 修复:存量清理——状态已签署却还带错误提示的记录
// UPDATE contract_record SET error_msg = NULL WHERE contract_status = 'SIGNED' AND error_msg IS NOT NULL;
两段改的是同一处:错误版在成功分支只改状态,展示端只看错误字段;修复版成功分支清掉错误标记,展示端先判断当前状态再决定是否展示错误信息,并补了存量清理。这次确认的只有“重试成功后历史错误信息未清理、后台据此误报”,没有实际改动的代码,上面是依据原因推导的方向,未实施也未验证。
下次遇到这些场景要警惕
- 准备把某个失败原因字段展示到后台之前:先确认它是“当前状态”还是“上一次执行的错误信息”,再数一遍存量里状态已成功、该字段仍有值的记录;条数不为零就先清存量或加状态判断,再上线展示。
- 改动签约结果回写逻辑时:列出这条记录上所有派生字段(状态、合同号、错误提示、可否自助处理),逐项写明成功和失败分支怎么处理;再完整跑一遍“失败 → 重试成功”,看详情页是否还留着上一次的提示。
- 排查“提示与实际不符”类反馈时:把合同记录、主表、快照的当前值摆在一起比,先确认哪一处准,再决定改展示还是补数据;不要拿着页面提示去重新签约或作废合同。
- 两份数据源都记同一份业务事实时(比如网点表和快照都记商户):对同一网点做一次字段级比对,确认写入和读取用同一来源,缺值由哪一侧补。