发生了什么

换电业务里,用户在电柜前扫码,把没电的电池放进格口,再取走一颗满电的。一台电柜分成若干格口,一个格口放一颗电池。现场取放电池要先由运维在系统里对这张工单执行开仓,把柜门打开,取放完再回工单结单。

工单是这次现场作业的凭据,按起因分成好几类:电池调入、电池调出、电柜满仓、到期未归还、找回。类型不同,现场要做的事不同,但最后都要落到同一个动作上——打开电柜的某个格口。

正常流程里,开柜页面只需要两样信息:运维打开工单详情点开仓,系统跳到开柜页面;页面把电柜编号和格口编号带过去调开仓接口,柜门打开后再由现场操作。这一步不需要知道是哪类工单,只要知道开哪个柜、哪个格口。

这次改动是为了新增一类“良品电池回收”工单:把柜里状态正常、还能继续用的电池取回来。这类单开仓时,系统还要知道取走的是哪一颗电池,于是给它单独做了一套开仓接口,比老接口多一个工单号参数。实现方式是:从回收单详情跳到开柜页面时,把工单号放进页面地址的参数里带过去;开柜页面看地址里有没有这个参数,有就调新接口,没有就调老接口。

问题是跳转这一处对每一类工单都把工单号带上了,没有判断“只有回收单才带”。于是电池调入、调出、满仓、到期未归还、找回这些单点开仓时,地址里同样带着工单号,开柜页面看到参数就一律调了新接口。新接口是围着回收单设计的,它要按这张单取到该格口里那颗电池的信息,取到才继续开柜;这些单不是回收单,取不到这份信息,接口直接返回“未找到该格口电池信息”,开仓流程在这里中断,柜门打不开。现场取不了也放不进电池,工单做不下去。

已确认的影响是 44 个操作用户、84 张工单:电池调入 51 张、电池调出 17 张、电柜满仓 11 张、到期 3 天后未归还 4 张、找回 1 张。

本质

原流程里,开柜页面只认电柜和格口,调哪个接口是固定的,不存在“选错接口”的可能。

新增回收单后,多了一条分支,页面需要知道“这次是不是回收单”,才能选对接口。这个信息本来应该由工单类型给出,实际实现却用了另一个信号:地址里有没有工单号。

  1. 产品给回收单加了一个专属场景:开仓要带上工单号,才能对上要回收的那颗电池。
  2. 前端在“工单详情跳开柜页面”这一处,把工单号写进地址参数。
  3. 开柜页面据此二选一:地址里有工单号就走回收接口,没有就走老接口。
  4. 第 2 步没有看工单类型,所有工单都写。工单号本来就存在于单据上,写进去不需要额外条件。
  5. 第 3 步的判断因此对所有工单都成立,五类非回收工单全部进了回收接口。
  6. 回收接口按工单号取不到该格口的电池信息,返回错误并中止流程,开仓失败。

用“某个参数有没有”来表达“这是哪类业务”,等于让所有旧入口默认走进新分支。参数是给跳转用的,它的存在范围由调用方决定;业务类型是单据自己的属性,必须显式判断。两者一旦混用,只要有一个入口多带一次参数,整条老链路就被改道,而且页面不会报“类型不对”,只会报下游的“没找到数据”,排查时很容易从接口往下查,反而离真正出错的那一步更远。

修复方向是在跳转处加类型判断:只有良品电池回收单才带工单号,其他工单不带;开柜页面仍然用“有没有工单号”决定走新接口还是老接口。记录里注明这次改动伴随发布与回滚,修复版本的上线与验证情况没有写明。

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

错误代码

// 工单详情页:点“开仓”跳到开柜页面
function goOpenCabinet(order) {
  router.push({
    path: "/cabinet/open",
    query: {
      cabinetNo: order.cabinetNo,
      gridNo: order.gridNo,
      // 为什么错:所有工单都带工单号,不只是回收单
      orderNo: order.orderNo,
    },
  });
}

// 开柜页面:用“地址里有没有工单号”区分回收接口
const { cabinetNo, gridNo, orderNo } = route.query;
// 为什么错:参数有无被当成“这是回收单”,非回收单也满足
const open = orderNo
  ? openGridForRecycle({ cabinetNo, gridNo, orderNo })
  : openGrid({ cabinetNo, gridNo });
open.then(() => message.success("已开仓"));

修复代码示例

// 工单详情页:点“开仓”跳到开柜页面
function goOpenCabinet(order) {
  const query = { cabinetNo: order.cabinetNo, gridNo: order.gridNo };

  // 只有良品电池回收单才带工单号:带了就意味着走回收接口
  if (order.type === ORDER_TYPE.RECYCLE_GOOD_BATTERY) {
    query.orderNo = order.orderNo;
  }

  router.push({ path: "/cabinet/open", query });
}

// 开柜页面:判断方式不变,此时带工单号的只剩回收单
const { cabinetNo, gridNo, orderNo } = route.query;
const open = orderNo
  ? openGridForRecycle({ cabinetNo, gridNo, orderNo })
  : openGrid({ cabinetNo, gridNo });
open.then(() => message.success("已开仓"));

下次遇到这些场景要警惕

  1. 给某一类单据新增专属参数时,先在跳转或发请求这一处列出所有会进来的单据类型,逐类实际点一次开仓,确认只有目标类型带上参数,其他类型仍走原接口。
  2. 用“参数有没有”当分支条件的地方,把它换成单据类型字段;传参时把类型显式带下去,而不是让接收方从参数有无反推。
  3. 老页面接入新单据时,不要在页面里新增一个只对新单据成立的条件,却让老单据继续经过同一段代码;发布前用老单据各走一遍,看请求落到哪个接口、返回什么。
  4. 接口新增必填入参后,按单据类型统计新接口的调用来源,出现非目标类型立刻告警,避免只看到接口报错量上涨,却不知道是谁调进来的。