删除 Comparison 配置后为什么保存失败？一个新手踩坑记录

·踩坑

问题描述

想象一个日常场景： 你手机上有个文件夹，里面存了 3 张照片。你把第 1 张删了，没问题；删第 2 张，也没问题；删第 3 张后，手机突然弹窗说："文件夹不能为空，请至少保留一张照片！"

是不是很困惑？明明我就是想清空这个文件夹啊！

在公司实习期间，我负责测试 Documind Workflow 系统，发现了类似的问题：

系统有一个 Comparison（对比）功能，用来对比上传的文件。某天测试时，我发现之前配置了 1 条对比映射（mapping），于是我按照测试计划尝试删除这个配置，把配置项删掉了。

删到最后一条时，点击"保存"，系统却报错：

builder.validation.mappings must contain at least one mapping when the validation stage is enabled

翻译一下："验证阶段已启用时，配置项不能为空"。

Bug 现象

测试场景

  1. 测试目标：一个已经配置过 Comparison 的 Workflow
  2. 进入 Workflow 的 Comparison 配置页面
  3. 看到之前配置了 1 条对比映射（mapping）
  4. 点击删除按钮，把这条映射删了
  5. 点击"保存"

系统的反应

保存失败，报错信息如上。

为什么会这样？

一句话解释：前端和后端对"配置已清空"的理解不一样。

前端的想法

  • "用户删掉了最后一条配置项，那这个功能就算清空了"
  • "我在页面上已经看不见任何配置项了，应该可以保存"

后端的想法

  • "虽然配置项列表空了，但这个功能本身还处于'启用'状态"
  • "启用的功能不能没有配置项，否则系统会出错"
  • "所以我拒绝保存空配置"

核心矛盾

前端只删了配置项，没有关闭功能本身。

就像你把文件夹里的照片删光了，但文件夹本身还处于"需要至少一张照片"的特殊状态。

如何复现这个问题？

如果你也遇到类似情况，可以按以下步骤验证：

  1. 找一个已经配置过 Comparison 的 Workflow
  2. 进入 Comparison 配置页面
  3. 把所有配置项（mappings）删掉
  4. 点击保存按钮
  5. 观察是否报错

临时解决办法

最快的方法：回到 Workflow 总览页面，找到 Comparison 这个功能，先关闭它，然后再保存。

操作步骤

  1. 点击页面左上角或面包屑，回到 Workflow 总览页
  2. 找到 04. Comparison（对比阶段）
  3. 取消勾选它
  4. 点击保存
  5. 再次进入 Comparison 配置页，确认配置项已清空

这样后端就知道："用户既删除了配置项，也关闭了功能，状态一致，允许保存"。

为什么后端会拒绝空配置？

这不是后端"故意刁难"，而是为了防止系统出错。

举例说明

假设你告诉系统："我要启用 Comparison 功能，但没有配置项"。

系统运行时：

  • 看到 Comparison 功能已启用
  • 试图执行对比操作
  • 却找不到任何对比规则
  • 不知道该对比什么文件

结果：Workflow 运行到这一步就会出错。

所以后端的校验逻辑是："启用的功能必须有配置项，否则容易出问题"。

技术细节（给开发者参考）

如果你是开发者，想了解更深层原因：

前端代码位置

  • 配置删除逻辑在 ValidationConfigPanel.tsx
  • 保存时只更新了 completedStages（已完成阶段），没有更新 enabledStages（启用阶段）
  • 配置适配器 config-adapter.ts 把空的配置项发给了后端

后端代码位置

  • 校验逻辑在 compiler_service.py
  • 检查条件：如果 saving_stage_id == 3 或 3 in enabled_stage_ids，且配置项为空 → 报错
  • 后端认为：只要功能还在启用列表，就不能接受空配置

状态不一致的根源

前端只删了配置项列表，但没有同步关闭功能本身（从 enabledStages 中移除）。

给新手开发者的建议

设计系统时

  1. 删除操作应该联动关闭功能

    • 用户删除最后一条配置项时，前端应自动关闭该功能
    • 或者保存前提示："您已清空配置，是否关闭此功能？"

  2. 前后端状态要同步

    • 前端不仅要删除配置项，还要把"功能启用状态"发给后端
    • 后端收到空配置时，如果功能已关闭，应该允许保存

  3. 增加友好提示

    • 不要只报错，还要告诉用户："请先关闭 Comparison 功能"
    • 或者提供一键关闭按钮

总结

这个 Bug 的本质是：前端和后端对"删除配置"的理解不一致。

  • 前端以为："删了配置项 = 功能已清空"
  • 后端以为："功能还在启用 = 不能接受空配置"

解决方法：回到总览页，先关闭功能本身，再保存。

教训：删除操作要考虑功能的启用状态，前后端状态要保持一致。

补充：还有个相关问题

关闭 Comparison 功能后，我上传多个文件时，系统仍然提示"只能上传 1 个文件"。

原来前端判断"是否启用 Comparison"时，会去看旧的配置项是否存在，而不是看当前功能是否启用。

类比：就像你关闭了文件夹的"必须保留照片"功能，但系统还检查文件夹里是否有旧照片残留。

这个问题会在另一篇博客详细说明。

发现日期：2026-07-06
背景：公司实习期间负责测试 Documind Workflow 系统
项目开发者：公司正式员工
问题分类：前后端状态不一致