发生了什么
网点与业主签订租赁合同时,要在电子签平台上生成合同并完成签署。网点后台会展示一条“签约进度”,业务据此判断这份合同是在生成中、签约中还是已签约。系统还会在本地保存一条合同记录,记录里存着合同编号、合同状态,以及发起时写入的来源编码;后续向电子签平台查询进度,就靠这个来源编码对应到同一份合同。
正常流程是:业务在网点后台发起签约,签约服务在电子签平台创建合同,本地先落一条“生成中”的记录;对方完成签署后,签约服务把合同编号和“已签约”状态写回这条记录,后台的“签约中”随之消失,业务可以继续下一步操作。
这一次,3 个网点先后反馈“签约中没有收到合同”。后台弹窗一直显示“合同进度:签约中”,也没有合同编号。业务无法确认合同是否生效,也无法继续后续操作,只能报给值班研发逐条反查。反查后发现,这些记录都停在“生成中、合同编号为空”;其中一类是电子签平台已经签完,完成状态却没有回到本地。
本质
问题出在“对方的完成状态由谁写回本地”这一步。
- 业务发起签约后,签约服务在电子签平台创建合同,本地记录处于“合同生成中”,合同编号为空,来源编码已经写入。
- 电子签平台完成签署后,不会主动通知本地。本地靠一条延迟消息触发回查:拿来源编码去问对方“这份合同生成好了吗”。
- 这一次回查发生在对方完成之前。按来源编码查合同返回空,程序转而查询“未生成原因”。对方返回的标记是空值或“仍在生成”,程序就把这次回查当成已处理完,直接结束,不再安排下一次。
- 对方随后完成签署,本地既收不到通知,也没有第二次回查,合同编号一直为空,状态停在“合同生成中”,后台便一直显示“签约中”。
- 本来还有一道对账任务可以兜底,但它只扫描“审批中且已通过”的记录,不扫描“生成中且合同编号为空”的记录,这批数据因此也被漏过。
即便对方明确返回失败,重试也要同时满足两个条件:错误信息命中配置中心里的关键字,且重试次数没有超过上限。关键字对不上或次数用完,同样会停在中间状态。
根因不是某一次查询失败,而是这份状态只有一次回查机会,失败后没有任何角色再接手。
短期处理是人工比对电子签平台的状态:已完成的补写合同编号和“已签约”,已作废的置为“已取消”,再刷新后台确认不再显示“签约中”。长期修复方向是让回查在结果未知时按退避继续重试,并把对账任务扩展到“生成中且合同编号为空超过一小时”的记录;修复上线状态待确认。
错误代码
// 合同号回查程序:延迟消息到点后,按来源编码查询电子签平台
void onQueryMessage(ContractQueryMessage msg) {
ContractDetail detail = signClient.queryBySourceCode(msg.getSourceCode());
if (detail == null) {
NoContractReason reason = signClient.queryNoContractReason(msg.getSourceCode());
// 为什么错:标记为空表示“还没生成完”,却当成可以结束
if (reason.getFlag() == null || reason.getFlag()) {
return; // 为什么错:直接结束,不重试,也没有下一次回查
}
// 为什么错:只有失败且命中关键字、次数没用完才重试,其余情况同样丢失
if (retryKeywords.matches(reason.getMessage()) && msg.getAttempt() < MAX_ATTEMPT) {
retryQueue.enqueue(msg.nextAttempt());
}
return;
}
recordMapper.markSigned(msg.getRecordId(), detail.getContractNo());
}
修复代码示例
// 修复后:查不到或仍在生成,都按“结果未知”安排下一次回查
void onQueryMessage(ContractQueryMessage msg) {
ContractDetail detail = signClient.queryBySourceCode(msg.getSourceCode());
if (detail != null && detail.isSigned()) {
recordMapper.markSigned(msg.getRecordId(), detail.getContractNo());
return;
}
if (detail != null && detail.isCancelled()) {
recordMapper.markCancelled(msg.getRecordId());
return;
}
if (msg.getAttempt() < MAX_ATTEMPT) {
// 与标记值无关,统一按退避排下一次回查
retryQueue.enqueue(msg.nextAttempt(), BACKOFF_SECONDS[msg.getAttempt()]);
return;
}
// 次数用尽仍未知:保留现场并告警,交给对账任务继续核对
alert.warn("contract status unknown after retries", msg.getRecordId());
}
// 对账任务补上“生成中且合同编号为空”的扫描分支
void reconcileGenerating() {
for (ContractRecord r : recordMapper.findGeneratingWithoutNo(ONE_HOUR)) {
queryAndFix(r); // 按来源编码反查:已签补写,已作废置取消
}
}
下次遇到这些场景要警惕
- 依赖对方异步完成状态:先确认对方有没有状态变更通知。只有回查时,写清多久查一次、最多查几次、次数用完后由谁接手,再判断能不能只查一次。
- 构造回查早于对方完成的时序:先让查询返回空,再让对方置为已签署,观察本地是否还会再次查询并写回合同编号,而不是只验证“首次查询就能拿到结果”。
- 上线对账或补偿任务前:列出所有“中间状态 + 关键字段为空”的组合,逐一核对这些组合是否在扫描条件里,不要只覆盖其中一种状态。
- 后台只显示笼统状态文案:补上合同记录编号和对方合同编号,让值班人员能直接定位是哪一条记录卡住,不必逐条反查。