发生了什么
换电网点要和场地出租方签租赁合同才能营业,合同有期限,到期前要续签。签约在外部电子签平台上由双方盖章完成,本地系统负责发起、记录进度和保存结果。
本地有两份数据决定运营看到什么。一份是合同记录,记录状态(生成中、签约中、已签约)、合同号和发起时写入的来源编码;来源编码是本地和平台对上同一份合同的凭据,查进度、收通知都靠它。另一份是网点状态,系统按合同是否有效把网点标成在营、待签约、停业或已过期,后台的签约时间也来自这里。
正常流程是:运营发起续签,本地先落一条生成中、合同号为空的记录,并把来源编码发给平台建合同;平台返回合同号后本地写回、状态转签约中;双方签完章,平台归档并回调本地,本地按来源编码找到记录,改成已签约、写入归档时间,网点签约时间和在营状态随之更新。
这一次,四个网点在 9 月 10 日上午发起续签。当天下午系统回查平台,没查到合同,只拿回一句失败原因:必输字段 createdBy 未传值。系统据此把这四份记录作废,把网点标成已过期,还写了一条“无签署权限”的错误。但平台在第二天上午把合同建了出来,9 月 13 日签署完成并归档。老合同随后到期,三个网点变成待签约或停业,一个仍在营但合同已过期,后台签约时间仍是老合同的。
本质
- 建合同是发给外部平台的异步动作。请求发出后平台是否已建成、稍后是否成功,本地当天下午并不知道,结论只能是结果未知,不能当成确定失败。
- 系统判断要不要作废,依据不是平台返回的错误码,而是拿失败原因这段文字去匹配一张回滚关键字清单。这次原因里出现 createdBy,正好命中。
- 命中后立即回滚且不可逆:合同记录被软删除(数据仍在表里,业务查询按未删除过滤,等于消失),网点被改成已过期,还写了权限错误。两个错误叠在一起:文案关键字分不清“平台明确拒绝”和“参数校验没过、稍后可能成功”,软删除又把后续回调唯一的关联凭据一起抹掉了。
- 平台随后建成合同、签署归档并发来完成通知。回调要按来源编码或合同号找回记录:合同号一直是空的,记录又被软删除,两条路都断了,程序直接返回,不报错也不补偿。
- 系统也没有对账任务比对“平台已归档、本地无有效记录”的组合,这次不一致没有兜底;老合同到期后,网点状态按本地已作废的数据推进,变成待签约或停业。
合同在平台真实存在且已签署归档,本地却认为续签从未发生。处置是人工恢复这四份记录并补发完成消息,把状态和签约时间改回来。修复方向是:是否回滚只看平台明确错误码;结果未知时退避回查并告警,不提前作废;软删除记录仍要能被完成通知按来源编码找到;再加对账,扫平台已归档、本地无有效记录或网点已过期的组合并自动补偿。修复上线状态待确认。
代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。
错误代码
// 回查电子签平台:没查到合同,只带回一句失败原因
ContractQueryResult q = signClient.queryBySourceCode(sourceCode);
if (q.getContract() == null) {
String reason = q.getFailReason(); // 例:"必输字段[createdBy]未传值"
// 为什么错:文案当分支条件,createdBy 也可能只是必填字段名
if (ROLLBACK_KEYWORDS.stream().anyMatch(reason::contains)) {
// 为什么错:平台结果还没确定,这里就做了不可逆回滚
contractMapper.softDelete(recordId); // 为什么错:软删除后按未删除再也查不回来
nodeMapper.updateLatestContractStatus(nodeId, "EXPIRE");
contractMapper.saveError(recordId, "合同创建失败,无签署权限");
return;
}
}
// 签署完成回调:只查未删除的合同记录
NodeContract c = contractMapper.findActiveBySourceCode(sourceCode);
if (c == null) {
return; // 为什么错:找不到就静默丢弃,平台已归档也回不来
}
contractMapper.markSigned(c.getId(), archivedAt);
修复代码示例
// 回查结果先分三类:已建成 / 明确拒绝 / 结果未知
ContractQueryResult q = signClient.queryBySourceCode(sourceCode);
if (q.getContract() != null) {
contractMapper.fillContractNo(recordId, q.getContract().getNo());
contractMapper.updateStatus(recordId, "SIGNING");
return;
}
// 只有平台明确返回不可重试错误码,才置为失败,且不删记录
if (q.isRejectedByCode()) {
contractMapper.markFailed(recordId, q.getErrorCode()); // 网点状态不动,留给人工确认
alert.warn("续签建合同被平台明确拒绝", recordId, q.getErrorCode());
return;
}
// 查不到、超时、参数校验:一律按结果未知,退避后再查,次数用尽告警
retryQueryLater(sourceCode, recordId, q); // 不软删除,也不回滚网点状态
// 回调按发起时落库的来源编码关联,软删除的记录也要能找回
NodeContract c = contractMapper.findBySourceCodeIncludeDeleted(sourceCode);
if (c == null) {
alert.warn("签署完成回调找不到合同记录", sourceCode, contractNo); // 不静默
compensateQueue.save(sourceCode, contractNo, archivedAt);
return;
}
contractMapper.restoreAndMarkSigned(c.getId(), contractNo, archivedAt); // 恢复记录并写入归档时间
下次遇到这些场景要警惕
- 用外部系统的错误文案做分支判断时:把关键字清单和对方的错误码枚举逐条对一遍,构造“必填字段缺失、参数校验失败”这类稍后可能自动成功的错误,观察它是否被当成不可恢复;文案只进日志,不参与决策。
- 准备软删除或回滚本地记录前:先确认对方那次调用是明确拒绝还是结果未知,并列出依赖这条记录的查询,包括回查、完成通知和对账;再构造“本地回滚后对方成功”的时序,确认通知还能不能定位到记录。
- 回调按合同号或来源编码反查时:在合同号尚未写回、记录已被标记删除的状态下发一次完成通知,看结果是静默返回,还是有告警并进入补偿队列。
- 上线对账任务前:列出“平台已归档、本地记录已删除或网点已过期”的组合,核对这些组合是否在扫描条件里,不要只扫签约中。