发生了什么

网点之间调拨电柜分两步:原网点先扫码做出库,柜子进入“调拨中”;运到目的地后,由目的地网点扫码签收,柜子才算落到新网点、完成入库。签收之前,程序会先读一遍这台柜子的状态,只有处于“调拨中”的柜子才允许签收。这道校验的作用是挡住没出库就签收、或者已经被签收过的柜子。

柜子的状态记在电柜资产表里,一台柜子一条记录,记录里有电柜标识、柜型和状态。正常顺序是:出库后柜子状态变成“调拨中”;到点扫码,签收读到“调拨中”,校验通过,记录随之落到目的地网点。

这次有一台柜子,运营人员正常扫码出库,到点去签收,页面直接提示“电柜不在调拨中状态,无法操作”,签收做不下去。核查资产记录,这台柜子的状态字段是空的。

这里要补一层背景:柜子会主动上报一条注册消息,把电柜标识和当前柜型报上来,系统靠这条消息维护资产档案。而这台柜子在资产表里原本没有档案,它现在这条记录就是消费注册消息时补插进去的:标识和柜型取自消息,状态一落库就是空。

本质

一句话:处理注册消息的程序在柜型变化时把状态清空,紧接着拿这份数据插了一条新记录,于是新档案从建立起就没有状态,签收的状态校验永远不可能通过。

  1. 注册消息里带柜子标识和柜型。处理程序先按电柜标识查资产表:查到就更新已有记录,查不到就新建一条。
  2. 这段处理里有一条判断:消息里的柜型与记录上的柜型不一致时,把电柜状态置空。代码只做了清空,没有同时给出一个新的状态值。
  3. 这台柜子在资产表里原本没有记录,程序走的是新建分支:标识、柜型取自消息,状态字段带着上一步的清空值一起写进新记录。
  4. 签收时校验读到的正是这条记录,空值和“调拨中”对不上,于是走拒绝分支,抛出“不在调拨中状态,无法操作”。
  5. 出库这一步骤本身没有报错,操作人看到的是成功,所以问题直到签收才暴露。只要“资产表里没有这台柜子”和“注册消息里柜型发生变化”同时出现,补插的记录状态就是空,签收必然失败,与出库操作是否规范无关。

报错文案只讲“不在调拨中”,会让排查方向偏向“是不是没做出库”,而真正要看的是这条记录有没有状态、状态是谁写进去的。

修复做了三件事:一是把库中状态为空的电柜记录订正掉,业务随之恢复;二是删掉柜型变化时清空状态的那段逻辑,修复于 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);
    }
}

库里那批状态为空的记录已经通过数据订正补回合法状态,签收随即可正常进行;对账任务的作用是防止同类空值再次长期存在,它替代不了写入侧的修复。

下次遇到这些场景要警惕

  • 按设备消息补建或覆盖档案时:把这个处理里所有“重置字段”的分支列出来,确认每个被清空的字段在同一段代码里都有明确的新值。构造“资产表没有这台设备 + 消息里柜型变化”的组合跑一遍,看落库记录的状态和柜型是否都完整。
  • 遇到“不在某某状态,无法操作”的报错时:先把校验读到的那条记录整行打出来,重点看状态是不是空、是不是来自别的写入口。空值不要当成“另一个业务状态”去解释,否则会一直往业务操作上找原因。
  • 给状态字段设默认值时:数据库默认值和应用写入路径要一起核对,新建分支、导入分支、消息消费分支都要确认写入了合法初始值,不能只靠改表结构。
  • 出现一次空状态拦截后:按设备标识做定期对账,把状态为空的记录扫描出来并接到告警;人工订正只能止血,不把写入入口修掉,同一条路径还会再产生。