发生了什么

网点是线下加盟经营的门店,系统里每个网点都挂着一份主合同,合同决定这个网点在什么时间范围内可以经营。合同有一个从签约中到已签约的状态:续签发起后,本地合同先记成签约中;商户在外部签约平台完成签署、平台确认生效后,平台会给内部系统发一条状态变更消息,本地合同随之改成已签约,网点记录上的最新合同状态也一起更新。

后台判断一个网点能不能关闭、也就是终止合作时,读的就是网点上的这个最新合同状态。签约中意味着续签还没走完,这时关闭会把合同晾在半路,所以后台直接拦截;已签约、已过期这类终态才允许关。

正常顺序是:续签完成,外部平台把合同置为已生效,平台发出状态变更消息,内部合同程序消费消息并把本地合同改成已签约,网点最新合同状态同步过去,后台放行关闭。

这次,一个网点在 3 月 23 日完成续签,外部平台侧状态已经是已生效,但那条状态变更消息没有送到内部合同程序。本地合同记录一直停在签约中,网点上的最新合同状态也停在签约中。8 月 25 日值班人员接到关闭这个网点的反馈,后台按签约中判定流程未结束,把操作拦了下来。

核查还看到两处相关事实:网点记录上的商户编号、商户名称是空的,合同和商户主体没有关联上;被这次续签替换掉的旧合同在 8 月 20 日已经到期。也就是说,从外部看这家网点早已完成续签,从内部看它一直卡在签约流程里。

本质

  1. 外部平台在合同生效时发出状态变更消息,内部合同程序收到后负责把本地合同和网点上的最新合同状态一起改掉。这次这条消息丢失,两个地方都没有变。
  2. 系统本来有一支定时对账任务,会扫描本地仍是签约中、外部可能已经生效的合同,回查外部状态后补同步。但它只扫最近 62 天内更新过的记录。
  3. 这份合同的最后更新时间是 3 月 23 日,到 8 月发现时已过去五个月,早已落在对账窗口之外,这支任务再跑多少遍都取不到它。
  4. 消息丢了以后,唯一能自动纠正它的就是对账任务;对账补不到,本地状态就永久停在签约中。后台每次读到的都是这个旧值,关闭操作每次都会被拦。
  5. 网点上的商户编号为空,说明签约成功时那一步关联也没有落到本地,重放回调时要把这一项一起回填。

一句结论:一次状态变更只靠一条消息传递,消息丢失后的补偿范围又覆盖不到历史数据,本地状态就没有任何路径能回到正确值。

这次的处理是人工补:按合同号调用签约重试接口重放一次回调,参数里带上合同号、目标状态已签约和商户编号;再把网点最新合同状态改成已签约、回填商户编号和商户名称;最后在后台确认网点可以正常关闭。同类历史数据也做了一次统一梳理。

修复方向有三处:对账任务改成按未到终态取数,不再用固定天数窗口卡历史合同;消息侧给状态变更加失败重试和丢失告警,让丢消息本身能被发现;后台读取状态时,对长期停在签约中的网点增加一次外部回查。修复上线状态待确认。

下面两段是脱敏教学示例,用于说明错误与修复思路,不代表实际项目源码或已上线实现。

错误代码

class ContractStatusCheckJob {
    void run() {
        // 为什么错:对账只扫最近 62 天内更新过的合同,
        // 更早丢失回调的记录永远进不了扫描结果,状态补不回来
        List<Contract> list = contractMapper.selectByUpdateTimeAfter(62);
        for (Contract c : list) {
            Contract remote = signClient.query(c.getContractNumber());
            if (!Objects.equals(remote.getStatusCode(), c.getStatusCode())) {
                contractMapper.updateStatus(c.getContractNumber(), remote.getStatusCode());
                dealerMapper.updateLatestContractStatus(c.getDealerId(), remote.getStatusCode());
            }
        }
    }
}

class DealerCloseService {
    boolean canClose(String dealerId) {
        Dealer d = dealerMapper.selectById(dealerId);
        // 为什么错:关闭判断只读本地同步过来的状态,从不回查外部
        if ("SIGNING".equals(d.getLatestContractStatus())) {
            throw new BizException("网点合同流程中,暂不能关闭");
        }
        return true;
    }
}

修复代码示例

class ContractStatusCheckJob {
    void run() {
        // 修复:按“未到终态”取数,不设更新时间窗口,历史合同也能补到
        for (Contract c : contractMapper.selectUnfinished()) {
            Contract remote = signClient.query(c.getContractNumber());
            if (remote.getStatusCode() != null && !remote.getStatusCode().equals(c.getStatusCode())) {
                syncContract(c.getContractNumber(), remote.getStatusCode()); // 合同与网点状态一起改
            }
        }
    }
}

class DealerCloseService {
    boolean canClose(Dealer d) {
        // 修复:本地停在签约中时回查外部,区分真没签完和回调丢失
        if ("SIGNING".equals(d.getLatestContractStatus())) {
            Contract remote = signClient.query(d.getContractNumber());
            if ("SIGNING".equals(remote.getStatusCode())) {
                throw new BizException("网点合同流程中,暂不能关闭");
            }
            syncContract(d.getContractNumber(), remote.getStatusCode());
        }
        return true;
    }
}

下次遇到这些场景要警惕

  • 给外部系统的状态变更接回调时,先构造一次消费失败:故意让处理逻辑抛异常,观察消息是被重试、进死信,还是被吞掉后确认。被吞掉的那条状态从此不会有人再改。
  • 有对账任务时,查清它的取数条件是时间窗口还是业务终态。如果按更新时间截取,就去库里找一条早于窗口、仍停在中间态的数据,看任务能不能捞到它;捞不到等于没有兜底。
  • 两个系统都存同一份状态时,核对一次两侧值:外部已生效、本地未同步的记录是否只靠回调修正,有没有回查入口。发现不一致要能人工重放,而不是只能改库。
  • 合同状态和网点主合同状态是两处存储,补数据时必须一起改。只改合同表,后台读网点字段仍然会拦截关闭。