发生了什么

电池退回工厂这件事,要分清两样东西。一是单据:城市仓要把一批电池退回工厂,得先提一张退货出库申请,审批通过后生成出库单,电池装车离仓,出库单才算完成出库。二是电池资产记录:资产系统里每块电池有一条记录,记着它当前算哪一类资产、处在哪一段,比如在仓、运输中、维保中。单据说明这次搬运走到了哪一步,资产记录说明这块电池的物权和使用状态,两者由不同动作维护。

正常流程是:电池实际离仓、出库单完成出库,系统再按业务需要上报资产状态。可实物和单据常常对不齐,工厂已经扫码签收了,城市仓的申请还挂着,出库单没生成或者没完成。为此有一个定时补偿任务:找出工厂已签收、又没能关联上退货申请的电池,把它们推给资产侧,匹配还没出库的那张退货申请,自动补一张出库单并置为已出库。

这次就落在了补偿任务上。一块电池在 9 月 2 日上午被工厂扫码签收,城市仓此前只提交了申请、没有走出库,补偿任务扫到它,自动补单出库。

按后来明确的规则,自动出库只补单据,不应该上报电池资产状态。实际结果是:补单完成后,这块电池的资产状态被改成了运输中,之后又变成维保中。实物已经在工厂、单据由系统补出来,资产台账上却多了一段运输中和维保中的记录,跟实物、跟这次补单的性质都对不上。

本质

一句话:出库后要不要上报资产状态,条件只写成“出库完成”,没有区分这张出库单是人工正常出库还是补偿任务补出来的,于是补单把不该发生的资产状态变更一起做了。

  1. 人工出库时,出库单完成之后上报资产状态是需要的:电池确实离仓上路,资产记录应当跟着变成运输中,返厂维修的再记成维保。
  2. 补偿任务做的是另一件事:实物早就到了工厂,缺的只是单据。它补单据,不该替这块电池再走一次“离仓上路”的资产变更。
  3. 两件事落在了同一段代码里。早期产品方案写的是“自动发货需要上报物权”,这段上报因此被当成自动发货的必备步骤,写进了共用的出库完成处理;补偿任务调用同一个方法,就把它一起带上了。后来资产上报的要求改成自动出库不上报,规则变了,调用没有变。
  4. 于是补单成功的同时,资产侧收到一次“运输中”的上报,之后资产状态又变成“维保中”。单据侧的结果是对的,资产侧多了一次变更。

补偿任务只需要补单据,却把“出库即上报资产状态”这个副作用一起执行了;单据补对了,资产记录被改错。

处理方案是在自动发货上报物权的地方加开关,默认 false,即自动出库不再自动上报物权,只保留人工出库的上报。开关上线后的验证结果尚未确认,修复上线状态待确认。

错误代码

// 教学示例:人工出库与补偿任务共用同一段“出库完成”处理
public void completeOutbound(OutboundOrder order, OutboundSource source) {
    order.setStatus(OUTBOUND_DONE);
    outboundRepo.updateStatus(order);

    // 为什么错:判断条件只看“出库完成”,不看这张单据是人工出库还是补单
    assetClient.reportStatus(order.getBatterySn(), AssetStatus.IN_TRANSIT);
    if (order.isReturnToFactory()) {
        assetClient.reportStatus(order.getBatterySn(), AssetStatus.IN_REPAIR);
    }
}

// 定时补偿:工厂已签收但单据未出库,自动补一张出库单
public void compensate(Long applyId) {
    OutboundOrder order = buildFromApply(applyId);
    outboundRepo.insert(order);
    // 来源传进去了,下游却没有用它决定要不要上报
    completeOutbound(order, OutboundSource.AUTO);
}

修复代码示例

// 修复示例:按出库来源决定是否上报,自动补单默认不上报
public void completeOutbound(OutboundOrder order, OutboundSource source) {
    order.setStatus(OUTBOUND_DONE);
    outboundRepo.updateStatus(order);

    boolean manual = source == OutboundSource.MANUAL;
    // 人工出库照旧上报;自动补单要开关显式打开才上报,默认值落在不上报一侧
    if (manual || assetReportSwitch.autoReportEnabled()) {
        assetClient.reportStatus(order.getBatterySn(), AssetStatus.IN_TRANSIT);
        if (order.isReturnToFactory()) {
            assetClient.reportStatus(order.getBatterySn(), AssetStatus.IN_REPAIR);
        }
    }
}

// 补单只补单据,资产状态保持原样
public void compensate(Long applyId) {
    OutboundOrder order = buildFromApply(applyId);
    outboundRepo.insert(order);
    completeOutbound(order, OutboundSource.AUTO);
}

下次遇到这些场景要警惕

  1. 补偿任务、定时任务要复用主流程的写操作时,先把那一步的全部副作用列出来:上报、通知、扣减、改状态。这次补单不该发生的,都要在方法入口按来源拦掉,不能靠调用方“记得别传”。
  2. 同一段代码有多个调用入口(人工、自动、导入、重试)时,逐个入口检查有没有“只有人工才该做”的动作;用来源参数或开关显式区分,并确认默认值落在安全的一侧。
  3. 产品规则变更时(例如“自动出库不上报资产状态”),拿变更点反查所有调用位置,尤其是这种补偿任务;只改调用方、不改共用方法,等于没改。
  4. 验证时造出“工厂已签收、单据未出库”的数据跑一次补偿,同时看单据状态和资产记录:单据应变成已出库,资产状态应保持原样;再走一次人工出库,确认上报仍然生效。