发生了什么

换电业务里,用户租到一辆电车后,电池并不是随车固定的:车上没电的电池可以放进网点电柜的空格,再从电柜里取一颗满电的装回车上。一颗电池装上车以后,下游的硬件逻辑要先确认它是被授权取出来的,这个确认在记录里叫“认证”。认证通过,电池才能持续放电;认证不通过,电池会在几分钟后自己断电,车走不了,仪表上的电量也会从满格跳到零。

正常取电要走完一条链路:操作人员在操作端发起取电,平台向电柜下发一条开仓指令,指令里带一个用户来源,记录里称作“指令用户来源”,用来说明这次开仓是哪条业务发起的。设备侧按这个来源走对应的处理,才会把取出的电池认作已认证、允许正常放电。也就是说,这个来源值不只是平台内部的一个标签,它决定设备接下来怎么对待这颗电池。

这次上线了一条面向租车业务的新操作入口。在这之前,开仓取电只有老的作业端应用一个入口;新入口带来了新的业务用户来源。这个新来源在平台内部是一个合法的枚举值,但设备侧认识的那组“指令用户来源”并没有增加对应的取值。新入口下发开仓指令时,没有把业务侧来源转换成设备认识的值,而是把它直接带了下去。

结果,柜门正常打开,电池也能取出来、顺利装上车,前几分钟一切正常;几分钟后电池断电,电量显示从满电掉到零。记录里只有一台车、一颗电池的反馈,没有写受影响的车辆和电池数量。应急处置是暂时只用老的作业端应用开仓取电,等参数调整后再验证新链路;研发方向是补上来源转换,让新链路下发的内容与老链路保持一致。

本质

一句话:新入口把业务自己的“用户来源”原样写进了给设备的开仓指令,没有换成设备认识的那个来源值,设备认不出这次开仓属于哪条业务,就把取出的电池按未认证处理,几分钟后切断放电。

  1. 原流程。老入口开仓时,平台先把自己的来源换成设备侧的“指令用户来源”再下发;设备在这个字段上只认识有限的几个值,认得的就按对应分支处理,把这次取出的电池登记成已认证。

  2. 新增入口。需求给租车业务加了一个新的用户来源。这个值在平台内部有意义,用来区分不同渠道发起的操作,但设备侧从来没有见过它。

  3. 出错的一步。新入口下发开仓指令时,来源没有经过转换:业务侧的来源值被直接写进“指令用户来源”。设备收到一个自己清单里没有的值,找不到对应的处理分支。

  4. 结果。设备对这颗电池的认证依赖来源来判断这次取出属于什么业务;来源对不上,认证就不通过。认证不通过时电池的放电受到限制,几分钟后自动断开。于是出现“满电装车、几分钟后归零”:电量是真的,断的是输出。

这一步不容易被发现,因为链路上每一环都给了成功信号:接口调用成功、柜门真的开了、电池真的取走了、车也能骑几分钟。错误不落在开仓环节,而落在设备对这颗电池的认证上,而且要等几分钟才显现。柜门开成功、电池取出来,都不代表这颗电池已经通过认证;跨接口传递来源这类身份值时,透传等于让下游替你猜。

修复方向是给下发指令补一层来源转换:新入口的来源在边界上映射成设备已支持的指令用户来源,与老入口下发的内容一致;映射表里没有的取值要显式拒绝并留下告警,不要默认放行。记录没有写修复是否已经上线。

下面两段 Java 是脱敏教学示例,只对比“直接透传来源”和“在边界做转换”,不代表实际项目源码或已上线实现。

错误代码

// 新入口下发开仓指令(脱敏教学示例)
public enum UserSource { OPERATOR_APP, RENTAL_APP }   // 平台侧的用户来源
public enum CommandUserSource { OPERATOR_APP }        // 设备侧只认这一个值

public class OpenCommandFactory {

    public OpenCommand build(OpenRequest req) {
        OpenCommand cmd = new OpenCommand();
        cmd.setCabinetNo(req.getCabinetNo());
        // 为什么错:平台侧来源原样当成指令来源下发
        // 为什么错:设备侧的来源清单里没有 RENTAL_APP,认不出这次开仓属于什么业务
        cmd.setCommandUserSource(req.getUserSource().name());
        return cmd;
    }
}

修复代码示例

// 同一个工厂类,只在边界补一层来源转换(脱敏教学示例)
public class OpenCommandFactory {

    public OpenCommand build(OpenRequest req) {
        OpenCommand cmd = new OpenCommand();
        cmd.setCabinetNo(req.getCabinetNo());
        // 修复:设备侧只接收它认识的指令来源,转换在这一层完成
        cmd.setCommandUserSource(toCommandUserSource(req.getUserSource()));
        return cmd;
    }

    private CommandUserSource toCommandUserSource(UserSource source) {
        switch (source) {
            case OPERATOR_APP:
            case RENTAL_APP:      // 新入口与老入口落到同一个设备侧来源
                return CommandUserSource.OPERATOR_APP;
            default:
                // 不在映射表里的来源直接失败并告警,不能带着未知值下发
                throw new IllegalArgumentException("未支持的取电来源: " + source);
        }
    }
}

下次遇到这些场景要警惕

  • 新增业务入口或用户来源时:先把所有会向设备或其他系统下发指令的位置列一遍,逐个确认边界上有没有来源转换;只加了下发入口、没改转换层,设备收到的就是一个它不认识的值。
  • 开仓类操作上线验证时:不要只看柜门开没开、电池取没取出来、接口有没有返回成功;按“取电—装车—放电几分钟”整个闭环跑一遍,观察电池是否被认证、中途是否断电。
  • 定义跨系统枚举时:把两端的取值列成对照表,新增值只要有一端缺失,就应当在边界拒绝并告警;默认放行或按未知值硬发,问题只会转移到最不容易观察到的那一环。
  • 灰度或双入口并存期间:老链路和新链路各取一颗电池做对照,确认两条链路下发的指令内容一致,避免只有一条路径上的用户遇到问题。