发生了什么
网点之间调拨电柜分两步:原网点先扫码做出库,柜子进入“调拨中”;运到目的地后,由目的地网点扫码签收,柜子才算落到新网点、完成入库。签收之前,程序会先读一遍这台柜子的状态,只有处于“调拨中”的柜子才允许签收。这道校验的作用是挡住没出库就签收、或者已经被签收过的柜子。
柜子的状态记在电柜资产表里,一台柜子一条记录,记录里有电柜标识、柜型和状态。正常顺序是:出库后柜子状态变成“调拨中”;到点扫码,签收读到“调拨中”,校验通过,记录随之落到目的地网点。
这次有一台柜子,运营人员正常扫码出库,到点去签收,页面直接提示“电柜不在调拨中状态,无法操作”,签收做不下去。核查资产记录,这台柜子的状态字段是空的。
这里要补一层背景:柜子会主动上报一条注册消息,把电柜标识和当前柜型报上来,系统靠这条消息维护资产档案。而这台柜子在资产表里原本没有档案,它现在这条记录就是消费注册消息时补插进去的:标识和柜型取自消息,状态一落库就是空。
本质
一句话:处理注册消息的程序在柜型变化时把状态清空,紧接着拿这份数据插了一条新记录,于是新档案从建立起就没有状态,签收的状态校验永远不可能通过。
- 注册消息里带柜子标识和柜型。处理程序先按电柜标识查资产表:查到就更新已有记录,查不到就新建一条。
- 这段处理里有一条判断:消息里的柜型与记录上的柜型不一致时,把电柜状态置空。代码只做了清空,没有同时给出一个新的状态值。
- 这台柜子在资产表里原本没有记录,程序走的是新建分支:标识、柜型取自消息,状态字段带着上一步的清空值一起写进新记录。
- 签收时校验读到的正是这条记录,空值和“调拨中”对不上,于是走拒绝分支,抛出“不在调拨中状态,无法操作”。
- 出库这一步骤本身没有报错,操作人看到的是成功,所以问题直到签收才暴露。只要“资产表里没有这台柜子”和“注册消息里柜型发生变化”同时出现,补插的记录状态就是空,签收必然失败,与出库操作是否规范无关。
报错文案只讲“不在调拨中”,会让排查方向偏向“是不是没做出库”,而真正要看的是这条记录有没有状态、状态是谁写进去的。
修复做了三件事:一是把库中状态为空的电柜记录订正掉,业务随之恢复;二是删掉柜型变化时清空状态的那段逻辑,修复于 12 月 23 日上线;三是增加按电柜标识的定期对账,把状态为空的记录捞出来告警,便于及时发现和恢复。
下面两段是脱敏教学示例,用于说明错误与修复思路,不代表实际项目源码或已上线实现。
错误代码
// 电柜注册消息处理(脱敏教学示例)
class CabinetRegisterHandler {
void onRegister(CabinetRegisterMsg msg) {
CabinetAsset asset = assetMapper.selectByMac(msg.getMac());
if (asset == null) {
asset = new CabinetAsset();
asset.setMac(msg.getMac());
} else if (!Objects.equals(asset.getCabinetType(), msg.getCabinetType())) {
// 为什么错:柜型变化时只把状态清空,
// 没有随后给出一个合法状态,清空值就被留在对象上
asset.setStatus(null);
}
asset.setCabinetType(msg.getCabinetType());
// 为什么错:新建分支不补初始状态,
// 空状态被当成普通字段一起落库
assetMapper.insertOrUpdate(asset);
}
}
修复代码示例
// 同一个入口(脱敏教学示例)
class CabinetRegisterHandler {
void onRegister(CabinetRegisterMsg msg) {
CabinetAsset asset = assetMapper.selectByMac(msg.getMac());
if (asset == null) {
asset = new CabinetAsset();
asset.setMac(msg.getMac());
asset.setCabinetType(msg.getCabinetType());
// 修复:新建档案必须自带初始状态,
// 不能指望后续业务动作再补
asset.setStatus(CabinetStatus.PENDING_INBOUND);
} else {
// 修复:柜型变化只更新柜型,状态由业务动作推进,
// 不再在这里清空
asset.setCabinetType(msg.getCabinetType());
}
if (asset.getStatus() == null) {
// 兜底:所有写入口都不允许空状态落库
asset.setStatus(CabinetStatus.PENDING_INBOUND);
log.warn("cabinet asset without status, mac={}", msg.getMac());
}
assetMapper.insertOrUpdate(asset);
}
}
库里那批状态为空的记录已经通过数据订正补回合法状态,签收随即可正常进行;对账任务的作用是防止同类空值再次长期存在,它替代不了写入侧的修复。
下次遇到这些场景要警惕
- 按设备消息补建或覆盖档案时:把这个处理里所有“重置字段”的分支列出来,确认每个被清空的字段在同一段代码里都有明确的新值。构造“资产表没有这台设备 + 消息里柜型变化”的组合跑一遍,看落库记录的状态和柜型是否都完整。
- 遇到“不在某某状态,无法操作”的报错时:先把校验读到的那条记录整行打出来,重点看状态是不是空、是不是来自别的写入口。空值不要当成“另一个业务状态”去解释,否则会一直往业务操作上找原因。
- 给状态字段设默认值时:数据库默认值和应用写入路径要一起核对,新建分支、导入分支、消息消费分支都要确认写入了合法初始值,不能只靠改表结构。
- 出现一次空状态拦截后:按设备标识做定期对账,把状态为空的记录扫描出来并接到告警;人工订正只能止血,不把写入入口修掉,同一条路径还会再产生。