发生了什么

网点是平台运营的一个线下点位,要和场地方签场地合同。合同不在本地生成,而是在电子签平台上创建并完成签署。网点后台为此保存一条本地合同记录,记住这份合同走到哪一步:生成中、签署中、已签署、已作废;网点主表另存一个“最新合同状态”,页面据此判断这个网点当前有没有生效合同。合同签成后,运营要换签或续签,网点页面上会出现“重新签约”入口,点进去就能发起一份新合同。

为了保证同一个网点不会同时谈两份合同,后台的判断很直接:只要本地还存在一份“进行中”的合同(生成中或签署中),入口就不展示。正常情况下这条规则没问题:合同签成,状态被改成已签署,入口随之出现;合同作废,状态被改成已作废,入口同样应该出现。

这次不一样。运营在电子签平台上把一份刚发起、还在签署中的合同作废了,回到网点后台刷新,页面仍然把这份合同显示为“签署中”,“重新签约”入口一直没有出现,业务没法发起新合同,只能把问题反馈过来。

研发核对后确认:电子签平台上这份合同已经是作废状态,本地合同记录却还停在“签署中”,网点主表的最新合同状态也还指着这份作废的合同。当天下午通过内部服务接口把本地记录订正为已作废,并把主表最新合同状态回退到上一份已签署的合同,入口马上恢复正常。确认影响是这一个网点在订正前无法发起新合同,网点本身的营业状态没有受影响。

本质

合同状态的权威来源是电子签平台,本地只是跟随。跟随的通道只有一条:签署完成消息。

  1. 运营发起合同时,签约服务先在本地写一条记录,状态是“合同生成中”,平台生成成功后改为“签署中”。
  2. 对方在平台上签完,平台推送“签署完成”消息,本地消费程序收到后把记录改成“已签署”,并继续执行签约成功后才该做的事,例如登记结算规则。
  3. 这次运营在平台上作废合同。作废是负向流转,平台不会推“签署完成”,本地消费程序也没有订阅别的状态消息,所以本地一条消息都收不到。
  4. 消费程序里同样没有“作废、撤回”的处理分支,本地没有代码会把这条记录改成已作废。
  5. 也没有定时任务去反查平台状态、订正停在中间态的本地记录。只要没人手工订正,记录就一直停在“签署中”。
  6. 网点页面判断入口时只看本地记录:还有进行中的合同,就认为这个网点还有合同在谈,入口继续隐藏。一条已经作废的合同,就这样把重新签约挡住了。

这种情况不能靠补发一条“签署完成”消息来修。消费程序收到后只会把状态置为已签署,还会继续登记结算规则;合同已经放弃,再按签成处理会带来新的错误数据。所以这次只能直接改本地状态。

状态同步只实现了“签成”这一条正向路径,合同被作废或撤回时,本地没有任何程序负责把它改回来。

修复方向是补上负向同步:平台作废、撤回时下发事件,本地按事件改为已作废并回退主表状态;再加一个定时对账任务,扫描长期停在生成中、签署中的记录,反查平台状态后自动订正并告警;入口判定之外保留一次平台实时状态兜底。本次订正已完成,这些改进的上线状态待确认。代码为脱敏教学示例,用来说明同步缺口与补法,不代表实际项目源码或已上线实现。

错误代码

// 状态回写入口:只监听“签署完成”这一种消息
@EventListener
public void onSigned(ContractSignedEvent event) {
    // 为什么错:唯一的回写入口只对应正向终态,平台作废、撤回时没有消息进来
    recordMapper.updateStatus(event.getRecordId(), "SIGNED");
    settlementService.createRule(event.getRecordId()); // 签成才登记结算规则
}

// 本地状态主要由“发起”和“签成”两处写入,作废分支不存在
// 也没有定时任务反查平台状态,记录停在“签署中”之后无人接手

// 网点页面判断是否展示“重新签约”入口
public boolean canResign(String dealerId) {
    // 为什么错:只看本地是否还有进行中记录,本地没被订正就永远挡住入口
    return recordMapper.countInProgress(dealerId) == 0;
}

修复代码示例

// 1. 负向流转同样落库:作废、撤回都改为本地已作废,且不再登记结算规则
public void onMessage(ContractStatusMessage msg) {
    switch (msg.getStatus()) {
        case SIGNED -> {
            recordMapper.updateStatus(msg.getRecordId(), "SIGNED");
            settlementService.createRule(msg.getRecordId());
        }
        case CANCELLED, WITHDRAWN -> recordService.markCancelled(msg.getRecordId());
        default -> log.warn("未处理的状态 {}", msg.getStatus()); // 留痕告警,不静默丢
    }
}

// 2. 对账兜底:扫描长期停在中间态的本地记录,以平台状态为准订正
@Scheduled(cron = "0 0 2 * * ?")
public void reconcileStuckContracts() {
    for (ContractRecord r : recordMapper.listStuck(Duration.ofDays(1))) {
        String remote = signClient.queryStatus(r.getSourceCode());
        if ("CANCELLED".equals(remote) || "WITHDRAWN".equals(remote)) {
            recordService.markCancelled(r.getId());
            alert.warn("本地合同状态已按平台订正", r.getId());
        }
    }
}

下次遇到这些场景要警惕

  • 状态由外部平台主导、本地只收一种“成功”消息:把平台的终态列全(签成、作废、撤回、过期),逐个确认本地是否有对应的同步通道;缺一个,本地记录就会永久停在中间态。
  • 页面入口按“是否存在进行中记录”隐藏:构造一条停在中间态的历史记录,看入口是否被挡住;入口的判定条件要和“这条记录还能不能继续推进”对齐,而不是和“历史上有没有发起过”对齐。
  • 新增“生成中、签署中”等中间态:同时准备一条按时间扫描的对账任务,超过约定时长仍未推进就反查平台并告警,不要等业务反馈才发现。
  • 准备用补发成功消息修数据:先确认消费程序收到后会不会继续执行建规则、建账单等后续动作;给已作废的合同补发成功消息,会把放弃的合同重新当成签成。