发生了什么

运维人员到现场检查换电柜(业务里叫电柜),要把每项检查结果逐条填进“电柜巡检工单”。一张工单里有很多行,每行叫一条巡检明细,明细上带一个 actionType 字段,标记这条明细属于哪类操作,比如开仓、关仓、普通巡检。明细填完提交,工单进入完成状态,详情页把这些明细展示出来,供后续查询和复核。

正常流程是:提交时程序遍历这张工单的全部明细做校验,必填内容没填、内容不符合要求的明细不允许提交。所以完成后的详情里看到的都是经过校验的内容。

这次不同在提交前的校验条件。电柜安装流程线上化的改造里,AI 辅助编码在同一段代码上发现注释和判断对不上:注释写的是“只校验必填项(actionType === 1)”,代码却是 if (item.actionType),只要明细带了这个字段就校验。AI 按“代码应与注释一致”把判断改成了等于 1,随这次改造上线。改造的回归按巡检主流程做,关仓这个分支没有回归。

5 月 18 日业务侧反馈:开关仓的巡检工单完成之后,详情内容异常。这类明细的 actionType 不是 1,改动后不再进入校验,本该被拦下的内容未经检查就保存了下来。

本质

先说清楚 actionType。它是明细行的类型标记,1 只是其中一个取值。if (item.actionType) 的含义是“只要这条明细有类型就校验”,覆盖全部类型;注释“只校验必填项(actionType === 1)”只描述了其中一类,范围比代码窄。

注释和代码对不上,只能说明其中一边过时,但不能默认注释正确:注释是说明文字,线上真正跑的是代码,业务实际依赖的也是代码的行为。AI 辅助编码把“不一致”当成“注释是对的、代码写错了”,于是把条件收窄成只认 1。条件一变,校验范围就从“所有带类型的明细”缩到“只有类型为 1 的明细”,开关仓这类明细全部跳过校验。把注释当成代码的正确版本,是这次改动的起点。

跳过校验的明细不需要内容完整,照样提交成功,工单完成后详情里就出现了异常内容。改动当时没有指明要验证哪些场景,回归只走了主流程,这条历史分支在测试环境没有暴露。

修复方式是把判断改回 if (item.actionType),并清除这次改动带出的错误提示。记录里问题单已处理完成;对已经完成的异常工单是否需要修正数据,没有说明。

错误代码

// 巡检明细:actionType 标记明细属于哪类操作,1 只是其中一种
void validate(List<InspectionDetail> details) {
    for (InspectionDetail item : details) {
        // 原判断是“带类型就校验”,这里按注释收窄成只认 1
        if (item.getActionType() != null && item.getActionType() == 1) {
            // 为什么错:actionType 为 2、3 的开关仓明细全部跳过校验,
            // 必填内容没填、内容不合规也能提交,工单完成后详情内容异常
            checkRequired(item);
        }
    }
}

修复代码示例

void validate(List<InspectionDetail> details, List<String> messages) {
    // 清掉上一轮残留的提示,避免旧错误信息继续显示
    messages.clear();
    for (InspectionDetail item : details) {
        if (item.getActionType() != null) {
            // 恢复原判断:只要明细带了 actionType 就校验,
            // 开关仓等非 1 类型的明细同样要过校验
            checkRequired(item, messages);
        }
    }
}

上面两段是脱敏教学示例,用 Java 表达同一段判断。原代码是脚本里的真值判断,含义相同、判空写法不同,不代表实际项目源码。修复只调整判断范围和提示清理,校验内容本身没有改动。

下次遇到这些场景要警惕

  • 注释和代码的行为不一致时:先把这段判断服务的场景全部列出来(本例是开仓、关仓、普通巡检),确认线上依赖的范围,再决定改代码还是改注释;不要默认注释是规范。
  • 条件从“有值”收窄成“等于某个值”:为每个取值各造一条明细走完提交,检查不该跳过的类型是否仍被校验,而不是只看改动覆盖的那一类。
  • 改造会影响老工单、老流程时:按功能分支列出回归场景,主流程之外至少各执行一次,尤其是一个字段区分多种操作的场景。
  • 校验逻辑变动之后:先用一条必填为空的明细提交,确认会被拦下;再打开已完成工单的详情,核对展示内容与录入内容是否一致。