多文件上传后第一次打开 Review 页面为什么是空的？

·踩坑

问题描述

想象一个日常场景： 你刚把 3 张照片上传到手机相册。马上打开相册文件夹，却发现里面什么都没有——文件夹是空的！

你会不会觉得奇怪："明明上传成功了，为什么看不见？"

再过几秒刷新一下，或者重新打开文件夹，照片突然又出现了。

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

某次测试时，我按照测试计划一次性上传了 3 个文件，这些文件属于同一个"多文件任务"（multi-file run）。任务运行到 Extraction Review（数据提取审核）阶段后，我马上点击"Go to Review"进入审核页面。

第一次进入时，页面是空的：

  • 看不见任何文件信息
  • 没有显示"3 个文件"的分组
  • 页面右侧也没有可编辑的字段
  • 整个页面看起来像没有选中任何审核项

Bug 现象

测试场景

  1. 测试目标：一个配置了数据提取阶段需要人工审核的 Workflow
  2. 按照测试计划上传 3 个文件，生成一个"多文件任务"（这 3 个文件会一起处理）
  3. 等任务运行到 Extraction Review 阶段（状态变成"等待审核")
  4. 马上点击"Go to Review"或进入审核页面

系统的反应

第一次进入时：

  • 页面只显示审核页面的外壳（标题、导航栏）
  • 但不显示具体的文件信息
  • 右侧没有可编辑的字段，只有空白区域

刷新后或第二次进入：

  • 文件信息突然出现了
  • 能看见 3 个文件的分组
  • 可以选中某个文件进行审核
  • 可以编辑和保存字段

为什么会这样？

一句话解释：页面加载太快，审核数据还没准备好。

类比说明

就像你在餐厅点餐后马上就冲进厨房想看菜做好了没有。厨房还在准备食材，当然什么都没有。

但如果你在门口等几秒，或者第二次再进去，菜已经准备好了，就能看见了。

技术层面的原因

前端的问题：

  1. 点击"Go to Review"时，页面直接跳转到审核页，没有等待审核数据准备好
  2. 前端没有"轮询机制"（定期检查数据是否准备好了）
  3. 页面拿到空的审核列表后，以为没有审核项，就直接显示空白

后端的问题： 多文件任务的审核项，是在查询接口中动态生成的（从一个审核任务"展开"成 3 个文件的审核项）。

如果用户进入得太快，后端可能还没来得及完全准备好这 3 个审核项的数据。

如何复现这个问题？

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

  1. 找一个支持多文件上传的 Workflow
  2. 一次性上传 3 个文件（这 3 个文件会属于同一个任务）
  3. 等任务状态变成"等待审核"
  4. 马上点击"Go to Review"进入审核页（不要等待太久）
  5. 观察页面是否为空
  6. 刷新页面或第二次进入，观察是否恢复正常

临时解决办法

最快的方法：刷新页面或第二次进入。

操作步骤

  1. 第一次进入审核页后，如果页面是空的，不要慌
  2. 点击浏览器刷新按钮（或按 F5）
  3. 或者回到上一层，再次点击"Go to Review"
  4. 第二次进入时，文件信息应该能正常显示

为什么后端会慢一点？

这不是后端"反应慢"，而是多文件任务的审核数据需要额外处理。

单文件 vs 多文件

单文件任务：

  • 只有 1 个文件
  • 后端直接返回 1 个审核项
  • 用户进入时数据已经准备好了

多文件任务：

  • 有 3 个文件
  • 后端要先查到"主审核任务"
  • 再根据这 3 个文件动态生成 3 个审核项
  • 数据准备时间比单文件稍长

如果用户进入得太快，前端可能拿到空列表或不完整的列表。

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

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

前端代码位置

  • 审核 Queue 加载逻辑在 useReviewQueueSelection.ts
  • 使用 React Query 查询审核列表，但没有配置 refetchInterval（轮询）
  • Go to Review 跳转逻辑在 WorkflowDetailPage.tsx，直接调用 buildReviewAllPageUrl()，没有等待审核项可见

后端代码位置

  • 审核列表接口在 review_service.py
  • 多文件审核项在 _expand_review_summaries_for_linked_documents() 中动态展开
  • 展开需要根据 run_input_files / run_document_ids 生成多个子项

数据还没准备好时的表现

  • 前端拿到空或不完整的列表
  • activeReviewKey 被置空
  • 页面显示"无选中项"，右侧不渲染审核内容

还有个潜在风险（待验证）

在调查这个 Bug 时，我还发现了一个可能的问题（目前还未完全确认）：

现象描述

在多文件审核页中，如果我切换到第 2 或第 3 个文件，修改字段后点击"Save Edits"，保存的数据可能写错目标。

  • 理想情况：修改第 2 个文件，数据应该写回第 2 个文件的记录
  • 风险情况：数据可能写到了第 1 个文件的记录（因为多文件任务可能有多个数据行，前端没有明确指定当前文件的记录）

类比说明

就像你在相册里选了第 2 张照片进行编辑，但保存时系统把修改写到了第 1 张照片上。

当前状态

这个风险目前还未完全确认：

  • 初期测试时确实出现了"写错目标"的现象
  • 后续复测发现，当时可能同时存在多个任务，导致判断混乱
  • 需要更精确的测试来验证是否真的存在这个问题

建议

如果你是开发者：

  • 增加一个回归测试：创建 3 文件任务，分别对第 2、第 3 个文件 Save Edits，检查是否写回正确的文件记录
  • 确认 Save Edits 路径是否始终绑定当前文件的 extraction row scope

给新手开发者的建议

设计多文件系统时

  1. 进入审核页要等待数据可见

    • 不要直接跳转，先检查审核项是否准备好
    • 或者进入后轮询检查，直到数据可见

  2. 前端要有轮询机制

    • 如果审核列表为空，不要立即显示空白
    • 定期重新查询（每 2-3 秒），直到拿到数据

  3. 明确指定保存目标

    • 多文件保存时，必须明确指定当前文件的记录 ID
    • 不要依赖"默认第一条记录"的逻辑

总结

这个 Bug 的本质是：页面进入太快，数据还没准备好。

  • 用户点击"Go to Review"马上进入
  • 前端没有等待或轮询机制
  • 后端多文件审核项需要额外时间展开
  • 结果：第一次进入时页面拿到空列表，显示空白

解决方法：刷新页面或第二次进入。

教训：多文件任务的审核页面要有等待机制，不要让用户看见空白页面。

发现日期：2026-07-06
背景：公司实习期间负责测试 Documind Workflow 系统
项目开发者：公司正式员工
问题分类：数据加载时序问题
相关风险：多文件 Save Edits 目标定位（待验证）