发生了什么

网点与平台签约后,合同状态由两处共同决定:电子签平台记录签署进度(签署中、已签署、已归档),网点后台保存一份合同记录,并按这份记录决定这个网点还能做哪些操作。合同签完并归档后,后台把网点认定为已签约;需要续签或变更时,页面展示“重新签约”入口,由运营发起一份新合同。

这次出问题的网点处于暂停营业、等待续签的状态。运营打开网点页,找不到“重新签约”按钮,但查合同又显示已正常绑定,看不出哪里不对。

核对后的事实是:电子签平台早已完成签署并归档,本地合同记录却从签署那天起一直停在“签署中”,一年多没有再变过。后台正是按这个状态判断流程还没走完,把入口隐藏了。合同状态更新不上去,运营就没有办法再发起签约,只能由研发处理数据后手动重投一次回调消息。

本质

正常流程是这样:电子签平台签完后发出“合同更新”回调,本地一个消费程序接收,把本地合同状态改为“已签署”;改完之后,网点才被当作已签约。这次的问题出在这个消费程序的事务范围上。

  1. 消费程序在同一个事务里做两件事:先把合同状态从“签署中”改为“已签署”,再顺手触发“按合同生成租金账单”的处理。
  2. 生成账单需要读取这份合同在系统中留存的一份副本,业务上叫“合同快照”。快照记录关键条款,供后续周期计算使用。
  3. 这次按回调里带的快照编号查过去,什么也没查到:记录不存在,或者已被标记删除。程序在计算租金周期的那一步抛出业务异常“合同快照为空”。
  4. 异常沿调用链一路回到事务入口,整个事务回滚,第一步的状态更新也一起被撤销,合同仍然停在“签署中”。
  5. 消费程序的外层捕获了异常,只写了一行错误日志,没有继续抛出,消息因此被确认消费,从外面看这次回调“处理成功”。
  6. 电子签平台按约定每天重投这条回调,程序每天走到同一个位置,再抛一次异常、再整体回滚一次。状态始终不动,日志里每天都有同样一条错误。

结果就是本地状态与电子签平台长期不一致。后台判断网点时只看本地状态,合同一直“签署中”,网点就被归进“流程进行中”的一类,页面按这份名单隐藏了重新签约入口。

同一事务里,后面那步会失败的附加业务把前面的状态更新一起拖回滚,异常又被吞掉,所以重投多少次都不会好。

修复方向有两条:状态回写与账单生成拆开,账单失败不再影响合同状态落库,失败后交给补偿任务重试;同时补齐缺失的合同快照,再重投回调消息验证状态能正常更新。修复上线状态待确认。代码为脱敏教学示例,用来说明事务边界与回滚的关系,不代表实际项目源码。

错误代码

@Transactional
public void onContractSigned(ContractSignedEvent event) {
    contractMapper.updateStatus(event.getContractId(), "SIGNED");
    // 为什么错:在同一个事务里继续做会失败的附加业务
    billTrigger.generateRentBill(event.getContractId());
}

// 账单链路深处,快照缺失直接抛业务异常
private void calRentContractExecutePeriod(Snapshot snapshot) {
    if (snapshot == null || snapshot.isDeleted()) {
        throw new BizException("合同快照为空"); // 异常冒泡,状态更新一起回滚
    }
    generatePeriod(snapshot);
}

// 消费入口捕获所有异常,只记日志,消息仍被确认
public void execute(Message message) {
    try {
        onContractSigned(parse(message));
    } catch (Exception e) {
        log.error("合同更新回调处理失败", e); // 为什么错:吞掉异常,重试也不会改变结果
    }
}

修复代码示例

public void onContractSigned(ContractSignedEvent event) {
    // 状态回写单独提交,不再被附加业务拖住
    transactionTemplate.executeWithoutResult(
        status -> contractMapper.updateStatus(event.getContractId(), "SIGNED"));
    // 账单生成改为提交后异步触发,失败可重试
    afterCommitPublisher.publish(new RentBillGenerateEvent(event.getContractId()));
}

@Transactional
public void generateRentBill(Long contractId) {
    Snapshot snapshot = snapshotMapper.selectByContract(contractId);
    if (snapshot == null) {
        // 缺少快照时登记待补偿,不打断已提交的合同状态
        compensationService.markMissingSnapshot(contractId);
        return;
    }
    generatePeriod(snapshot);
}

// 消费失败向上抛出,交给消息重试与死信
public void execute(Message message) {
    onContractSigned(parse(message));
}

下次遇到这些场景要警惕

  • 给状态回写的事务里加同步业务:先把事务内所有步骤列出来,逐个问“这一步失败能不能让主状态不落库”,答案是不能的就移出事务或改为提交后异步执行。
  • 消费程序 catch 住异常后继续返回:检查 catch 之后消息是否仍被确认;如果异常会导致业务数据回滚,必须上抛或写入可重试的失败记录,否则重投只会重复同一次失败。
  • 页面入口按状态集合隐藏:把“入口为什么不展示”逐条对到具体状态值,不要只看页面配置;同时核对本地状态与外部签署平台是否一致,差异超出预期就查回调的消费结果。
  • 长期停在中间态的记录:先看更新时间和回调日志里是否有反复失败,确认事务是否回滚,再考虑补数据;不要直接手改状态掩盖回滚原因。