发生了什么

网点以合同方式取得经营资格,一份合同有生效日、到期日和履行期。合同签署完成时,系统不会直接把合同改成“履行中”,而是先登记一条“合同状态变更”任务,到生效当天由后台调度执行:把新合同的状态改成“履行中”、开始日写成生效日;把被替换的旧合同改成“已履行”、结束日写成生效日前一天。网点管理页面读的是“网点登记的主合同”,所以只有这条任务执行成功,页面上的履约期才会切到新合同。

正常顺序是:重新签约之后,新合同签署完成、先停在“待履行”;到生效当天任务执行,新合同开始履行、旧合同收尾、网点主合同指向新合同,页面显示新的履约期。

这次有一批网点在 8 月 21 日重新签约,两个网点的新合同分别在 9 月 16 日和 9 月 23 日生效。生效当天凌晨,合同状态变更任务被调度起来,执行到更新合同快照时抛异常退出。到 10 月 8 日核查时,两个网点是同一个样子:新合同还停在“待履行”,旧合同还是“履行中”且没有结束时间,网点登记的主合同仍指向已经到期的旧合同,所以页面上的合同状态显示“已到期”,履约期也是旧的。网点本身还落在“暂停运营”。当天系统发过一条任务执行失败告警,但这两条没有人跟进。

核查时还发现,库中另有 431 条同类“合同状态变更”任务逾期未执行(2025 年 184 条、2026 年 247 条),其中是否还有“重新签约后没接手”的网点,尚未逐条确认。

本质

任务里预置的目标值是对的。重新签约时,系统已经为这两份新合同建好了合同状态变更任务,写明“新快照改为履行中、开始日为生效日”“旧快照改为已履行、结束日为生效日前一天”。问题出在执行这一步。

  1. 生效当天,调度按触发日期取到任务,开始更新合同快照。
  2. 快照里有一个营业执照照片字段,在数据库中是 json 类型,驱动读出来是 JSON 对象而不是字符串。写回时程序直接把它塞进了字符串参数,抛出类型转换异常。
  3. 同一张快照里另一个照片字段做了“JSON 对象取文本”的转换,唯独这个字段漏了。只要网点登记过营业执照照片,这类任务就必然失败,不是偶发。
  4. 失败之后,任务状态没有被写成“失败”,仍然停在“待执行”;而调度只扫描“触发当天”的任务,过了当天不再补跑,所以这条任务从 9 月一直挂到核查当天。
  5. 网点状态是“暂停运营”时,自动恢复逻辑只在“待运营”“运营中”状态下生效,不会把已暂停的网点改回运营中,所以也不会自愈。

最终的错位是这样形成的:新合同签好了但没有接手,旧合同没有收尾,网点主合同还指向旧合同;页面读旧合同,就显示旧履约期和“已到期”。生效当天同类任务执行成功的有数十条,只有这两条带营业执照照片的数据失败,说明它与数据内容有关,与调度本身无关。

修复方向是:补上这个字段的类型转换,让同类 JSON 字段走同一个转换入口;任务失败时写入“失败”状态并保留告警;调度增加对“已过期仍未执行”任务的补跑或兜底扫描。数据侧还要把这两条任务补跑执行、把网点状态订正为“运营中”,并核对其中一家网点的合同类型(登记为“暂停营业正式合同”)。修复上线状态待确认。

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

错误代码

class ContractSnapshotUpdater {
    void update(Snapshot snap) {
        Map<String, Object> row = new HashMap<>();
        row.put("performance_status", "PERFORMING");
        row.put("start_date", snap.getStartDate());
        // 为什么错:营业执照照片在库里是 json 类型,
        // 驱动返回的是 JSON 对象,这里当成字符串直接写入,抛类型转换异常
        row.put("business_license_photos", snap.getLicensePhotos());
        snapshotMapper.updateByContractId(snap.getContractId(), row);
    }
}

// 调度侧:没有捕获异常,失败后状态既不写“失败”,
// 调度又只扫“触发当天”的任务,过了当天永远不再补跑
void execute(Task task) {
    updateSnapshot(task.getTargetId());
    taskMapper.updateStatus(task.getId(), "DONE");
}

修复代码示例

class ContractSnapshotUpdater {
    void update(Snapshot snap) {
        Map<String, Object> row = new HashMap<>();
        row.put("performance_status", "PERFORMING");
        row.put("start_date", snap.getStartDate());
        // 同类 JSON 字段统一走转换入口:先取文本,再按 json 写入
        row.put("business_license_photos", JsonValues.toJsonText(snap.getLicensePhotos()));
        row.put("other_photos", JsonValues.toJsonText(snap.getOtherPhotos()));
        snapshotMapper.updateByContractId(snap.getContractId(), row);
    }
}

void execute(Task task) {
    try {
        updateSnapshot(task.getTargetId());
        taskMapper.updateStatus(task.getId(), "DONE");
    } catch (Exception e) {
        // 失败必须落“失败”状态并保留告警,供补跑和排查
        taskMapper.updateStatus(task.getId(), "FAILED");
        alarm.send(task, e);
        throw e;
    }
}

两个网点还需要把这两条任务补跑一次,执行后新合同才会接手、旧合同才会收尾;扫描侧要对超过生效日仍停在“待执行”的任务做兜底补跑,否则同一类数据还会再次滞留。

下次遇到这些场景要警惕

  • 合同、协议签署后由任务改状态:把网点主体上所有 json 类型字段列出来,确认写入走同一套转换;准备“有照片”和“没照片”两种数据各跑一遍,看任务是否都能执行成功。
  • 任务执行报错之后:先查任务状态有没有被写成“失败”。如果调度只扫当天,就必须验证跨天补跑能把它重新捞起来,否则数据会长期停在半更新状态。
  • 把网点改成暂停、重新签约这类操作:确认自动恢复的覆盖范围,暂停状态在不在白名单里;不在就要准备人工订正步骤,不能等系统自愈。
  • 重新签约上线后做一次三处比对:新合同状态是否为“履行中”、旧合同是否有结束时间、网点主合同是否指向新合同,三者一致才算交接完成。