发生了什么

换电柜给骑手换电池,柜内每个仓格放一颗。柜子满了收不进电池,柜里电池不够又满足不了换电,系统因此给一线运维生成工单:满仓工单要求把多余电池调出,缺电时的调拨工单要求把电池调入。运维到现场后用手持作业端打开柜门,取走或放入电池,再回工单里把这张单标记完成。

一次正常的开柜作业要串起四个角色。工单程序建单并派给运维;手持作业端调用开仓接口,把这次操作的开仓单号一并传给电柜控制程序,单号是唯一编号,用来把开柜动作和回传对应起来;控制程序把开仓指令下发给电柜;电柜开门,并把开仓单号随结果回传。履约程序按回传的单号找到这次开柜记录,确认是哪个运维开的柜,再给工单程序发一条"运维取还电"消息。工单程序收到这条消息,才在工单上记一条调度记录,工单才能完成。

2026 年 3 月 19 日晚,工单程序和控制程序一起发版。工单侧为把工单和开仓记录关联起来,给开仓接口加了一个由自己生成的开仓单号入参,长度 18 位;控制程序原来自己生成 19 位单号,发版后改成入参非空就用入参、为空才自己生成。

3 月 20 日上午 10 点 19 分,一名运维到现场开柜取电。手持作业端把工单程序生成的 18 位单号传下去,开仓指令也下发到了电柜。电柜回传时把单号多报了一位,变成 19 位。履约程序拿 18 位去匹配,没找到记录,就把这次开柜记成"物理开仓":只记柜门开了,不关联运维,也就没给工单程序发取还电消息,工单上没有调度记录。

5 秒后,履约程序识别到柜子没满,发出一条"非满仓"消息。工单程序收到后去查本单运维的取电记录,没查到,判断这次开柜不是本单运维处理的,于是把满仓工单自动取消了。运维打开工单,看到的是已取消。

已确认的影响是部分型号电柜的电池调入、调出和满仓工单:开柜后工单记录不完整,工单无法正常完成。现场可改用另一套换电柜操作入口继续作业。

本质

一句话:开仓单号原来只有控制程序一个生成方,这次多了一个,两边的长度约定又不一样,电柜回传时还补了一位,履约程序按单号匹配自然找不到,运维的开柜被当成了无人认领的物理开仓。

  1. 原流程。控制程序生成 19 位开仓单号,随指令下发,电柜按原样回传,履约程序按这个单号能稳定找到记录,再通知工单程序记调度记录。这条链路里,单号是唯一的对应依据。
  2. 这次的改动。工单程序为把工单和开仓记录关联起来,改成自己生成 18 位单号,经手持作业端传给开仓接口;控制程序见入参非空就直接使用。单号从 19 位变成 18 位,但电柜侧仍按旧长度处理,回传时多报一位。
  3. 出错的一步在单号的约定上。同一个单号有了第二个生成方,长度却按各自方便来定,设备固件和历史记录都还按旧长度工作,匹配依据从源头就对不上。
  4. 履约程序匹配不到,按兜底逻辑记成物理开仓。这个兜底本身不算错,错在它把"匹配不到"直接当成"不是运维开的",于是不再发取还电消息,工单从此失去这条记录。
  5. 工单程序随后收到非满仓消息,按"没有本单运维的取电记录"判断这次操作与工单无关,自动取消满仓工单。两个程序都在按自己的规则执行,冲突点落在单号上。

修复方向有两条:一是工单程序不再自己生成单号,改成从控制程序获取,由控制程序统一生成,长度只有一个来源;二是电柜侧补上不同长度单号的处理,按型号逐步升级;部分老电柜已停止维护,覆盖不全。修复上线和验证结果待确认。

下面两段代码为脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现;单号长度与方法名均为示意。

错误代码

// 工单侧自行生成开仓单号,履约侧按单号精确匹配回传(脱敏教学示例)
public class OpenCabinetService {
    // 为什么错:单号长度按本服务的需要定成 18 位,
    // 而电柜回传和履约侧匹配仍按 19 位的旧约定工作
    private static final int SEQ_LEN = 18;

    public String open(String cabinetNo, String operatorId) {
        // 为什么错:同一个开仓单号出现第二个生成方,
        // 控制程序见入参非空就照用,长度从此有两个来源
        String optSeqId = String.format("%0" + SEQ_LEN + "d",
                Math.abs((operatorId + System.nanoTime()).hashCode()));
        cabinetClient.open(cabinetNo, optSeqId);
        return optSeqId;
    }
}

// 履约侧收到电柜回传后按单号找开柜记录
public void onCabinetReport(String cabinetNo, String reportedSeqId) {
    OpenRecord record = openRecordMapper.selectBySeqId(reportedSeqId);
    if (record == null) {
        // 为什么错:匹配不到就记成物理开仓,不告警也不关联运维,
        // 工单侧从此收不到取还电消息,整条业务闭环断在这里
        fulfillmentService.savePhysicalOpen(cabinetNo);
        return;
    }
    fulfillmentService.bindOperator(record, cabinetNo);
}

修复代码示例

// 修复:单号只在控制程序生成,回传异常先告警(脱敏教学示例)
public class OpenCabinetService {
    private final CabinetControlClient controlClient;

    public OpenRecord open(String cabinetNo, String operatorId) {
        // 修复:工单侧不再自己生成,改为向控制程序取号,长度只有一个来源
        String optSeqId = controlClient.nextSeqId(cabinetNo, operatorId);
        cabinetClient.open(cabinetNo, optSeqId);
        // 修复:本次使用的单号立即落库,后续始终按同一个值匹配
        return openRecordMapper.insert(cabinetNo, operatorId, optSeqId);
    }
}

public void onCabinetReport(String cabinetNo, String reportedSeqId) {
    // 修复:回传单号和约定格式不符时不再静默转物理开仓,先留痕并告警
    if (!seqRule.matches(reportedSeqId)) {
        alertService.warn("cabinet_report_seq_mismatch", cabinetNo, reportedSeqId);
    }
    OpenRecord record = openRecordMapper.selectBySeqId(reportedSeqId);
    if (record == null) {
        // 修复:仍兜底记物理开仓,但带上告警,失联能被人工发现
        fulfillmentService.savePhysicalOpen(cabinetNo);
        alertService.warn("open_record_not_matched", cabinetNo);
        return;
    }
    fulfillmentService.bindOperator(record, cabinetNo);
}

两段代码改的是同一处:错误版让工单侧自己造单号、匹配不到就静默转成物理开仓;修复版把单号收敛到唯一生成方,并让格式不符和匹配失败都留下可见信号。电柜固件对长度变化的兼容仍要单独排期,代码只解决匹配依据的来源问题。

下次遇到这些场景要警惕

  • 把跨系统匹配用的编号改由新的一方生成时:先列出所有会读这个编号的地方:设备固件、离线任务和历史数据,确认长度与格式约定一致;别只看两个后端服务之间的接口文档。
  • 新增入参并让下游"有值就用"时:分别构造入参为空、长度不符、含非数字字符三种输入,观察下游是拒绝、兜底还是静默降级;凡是静默降级,都必须带告警。
  • 评估这类变更的影响面时:用现场最老的设备型号走一次完整闭环,从开柜一路到工单完成;只在新设备上验证,覆盖不到存量设备。
  • 兜底分支把"匹配不到"解释成业务含义时:先确认这个解释在数据缺失时也成立,否则一次编号对不上就会被读成"不是本单运维操作"。