发生了什么

商户要在某个点位开店,先得和场地方签一份合同。这份合同不在自己的系统里生成,而是拿到外部的电子签约平台去签署:系统先建一条合同记录,合同号留空、状态是签署中;商户在平台上签完,平台把合同归档,系统再回头去问平台要合同号,把这条记录改成已签约。

合同状态不只是后台页面上的一行字,它决定这个点位能不能开始运营。签约之前,系统里只登记了一个“潜在网点”——意向已经有了、合同还没签完的点位;等合同状态变成已签约,另一段程序才会把这个潜在网点转成正式网点,商户之后才能对它做门店、设备、结算这些操作。合同号回写和状态变更是一条链上的两步,前面没走完,后面就不会发生。

这一次,一个点位的合同在平台上已经签署完成并归档,平台侧确认无误。但本地这条合同记录的合同号一直是空的,状态也没到已签约,对应的潜在网点始终没有转成正式网点,商户在后台做不了后续运营。确认影响是这一个潜在网点,没有资金损失。

本质

问题不在合同有没有签成,而在签完之后那次回查失败了,失败之后没有程序再接手。

  1. 合同号由平台生成,本地只能回查。平台在签署完成时会通知商户侧,但通知里不带完整的合同信息,所以系统收到通知后不直接处理,而是先排一条延迟消息,过一段时间再拿发起时写下的来源编码去平台查这份合同。
  2. 这次延迟消息到点执行回查时,平台以限流拒绝了请求。限流属于可恢复的失败:对方只是暂时不接受这个频率的请求,隔一会儿再问通常就能拿到结果。
  3. 这段处理没有把限流交给重试。异常发生之后这次消费就结束了,这条回查的重试次数一直是 0,之后既没有第二次回查,也没有别的程序把这一条自动补回来,最后只能人工订正。
  4. 本地合同记录于是停在签署完成之前的样子:合同号空、状态没到已签约。
  5. 把潜在网点转成正式网点的那段程序,是靠“合同状态变成已签约”这件事触发的。状态没有变,触发它的消息不会产生,这段程序一次都没有执行。网点没生成,不是生成程序算错了什么,是它根本没有被叫到。

一次可恢复的限流被当成了这次处理已经结束,合同号没写回,后面的状态变更和网点生成就一起停住了。

处理是人工补的:按平台已经归档的合同,把合同号写回这条记录、状态改成已签约,再触发一次生成,把潜在网点转成正式网点。

修复方向有三条。一是把限流、超时这类可恢复失败单独识别出来,按退避排下一次回查,并让重试次数真实递增;二是次数用完仍然失败时进死信并告警,留下可重放的记录;三是对“签署完成但合同号为空”的记录做对账,主动再查一次。后续的一次需求已经补上了针对限流的重试,这次补丁的上线与验证状态,现有信息没有说明。还有一个没有结论的点:这次延迟窗口设的是 180 秒,它是否总能覆盖平台创建合同所需的时间,无法确认。

下面的 Java 代码为脱敏教学示例,用于说明“限流失败没重试,回写没执行,下游网点生成不触发”的机制与改法,不代表实际项目源码或已上线实现。

错误代码

// 合同回查:延迟消息到点后去平台拿合同号,再回写状态(示意)
public void onQueryMessage(SignQueryMessage msg) {
    SignContract detail;
    try {
        detail = signClient.queryBySourceCode(msg.getSourceCode());
    } catch (RemoteException e) {
        // 为什么错:限流、超时都落到这里,只打一行日志就返回
        log.warn("query sign contract failed, source={}", msg.getSourceCode());
        return; // 为什么错:正常返回等于消费成功,消息不再重投,重试次数停在 0
    }
    if (detail == null) {
        return; // 为什么错:对方还没生成完也直接放弃
    }
    ContractRecord record = contractMapper.getBySourceCode(msg.getSourceCode());
    record.setContractNo(detail.getContractNo());
    record.setContractStatus(SIGNED); // 为什么错:只有走到这一步,状态才会变
    contractMapper.updateSigned(record);
}

// 网点生成:只在合同状态变成已签约时被触发(示意)
public void onStatusChanged(StatusChangedEvent event) {
    if (event.getToStatus() != SIGNED) {
        return;
    }
    outletService.createFromPotential(event.getContractId()); // 上面没回写,这里永远不执行
}

修复代码示例

// 合同回查:限流和超时都当可恢复失败,先排下一次再返回(示意)
public void onQueryMessage(SignQueryMessage msg) {
    SignContract detail;
    try {
        detail = signClient.queryBySourceCode(msg.getSourceCode());
    } catch (RateLimitedException | TimeoutException e) {
        // 可恢复失败:先把下一次回查落下,再正常返回,任务不会丢
        scheduleNext(msg, "recoverable");
        return;
    }
    if (detail == null) { scheduleNext(msg, "not created yet"); return; } // 对方还没生成完,也要再问
    ContractRecord record = contractMapper.getBySourceCode(msg.getSourceCode());
    record.setContractNo(detail.getContractNo());
    record.setContractStatus(SIGNED);
    contractMapper.updateSigned(record); // 状态落库后,下游才有状态变更可消费
    eventPublisher.publish(new StatusChangedEvent(record.getId(), SIGNED));
}

// 重试收口:次数用完进死信并告警,留一条可重放的记录
private void scheduleNext(SignQueryMessage msg, String reason) {
    if (msg.getRetryCount() >= MAX_RETRY) {
        alarm.warn("sign query retry exhausted", msg.getSourceCode(), reason);
        deadLetter.save(msg);
        return;
    }
    retryQueue.enqueue(msg.nextRetry(RETRY_DELAY)); // 退避一段时间再来一次
}

下次遇到这些场景要警惕

  1. 给“回查第三方拿关键字段”的消费加 try-catch 时,先把限流、超时、临时不可用和“对方确认没有这份数据”分开,再分别处理。造一次限流,看是否排了下一次回查、重试次数是否真的递增、次数耗尽后是否进死信,而不是只看日志里有没有一行报错。
  2. 关键字段回写靠状态变更消息串到下游动作时,故意让回写失败一次,确认下游生成动作还有对账或重放能补上。只验证“消息发出去了”不够,要验证“消息没发出去时谁来兜”。
  3. 设延迟窗口等对方生成数据时,先拉一段时间内对方创建实际耗时的分布,确认窗口能覆盖绝大多数情况;落在窗口外的那些,要继续回查,不能当成终态。
  4. 排查“平台已归档、本地没记录”时,先按发起时写下的来源编码比对两边状态:本地有记录但合同号为空,是回查失败;本地连记录都没有,问题在通知没到或消费没开始。两种断点的处理完全不同。