droboticflow/docs/architecture/annotation-pool-loading.md

65 lines
7.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 标注任务池读取与分页
2026-10-21,继展示分层与保存协调之后的第三阶段。实现位于同一仓库,前端复用现有 HTTP 客户端;公司环境尚未部署本轮改动。
## 职责
`src/lib/annotation-project-loading.js` 新增 `loadAnnotationPoolPage`,集中选择管理员、标注员侧栏及普通项目/审核工作区的读取协议,返回任务池、关联任务、游标和管理员计数。它不直接更新 React 状态,不接管领取或正式审核写入。
- 管理员标注池仍使用单次 `adminPool` 响应,筛选、总量、任务和游标来自同一服务器查询。
- 标注员首屏仍由 `loadOwnedAnnotationProject` 提前发布可用侧栏,不等待慢计数或辅助元数据;续页复用同一侧栏读取与旧 API 兼容规则。
- 质检、验收及其他非管理员工作区根据服务端可见任务池的任务 ID 关联任务,不用最新导入窗口替代,避免旧返工任务被新导入任务挤掉。
- 验收继续复用 `humanLoopApi.listAcceptancePools`,保留普通验收与包前验收两阶段、完整分页、版本去重及服务端授权。
- 普通管理员项目视图保留任务窗口分页,服务端 `canClaim` 及展示字段原样传递。审核工作区继续下推阶段筛选,已审核历史查询仍保留原口径。
页面保留项目元数据、辅助报表、提交后的临时展示覆盖和错误恢复 UI。首屏只有整组依赖成功且请求序号、页面范围均有效,才接收任务池及游标;元数据失败不会提前推进游标或发布管理员计数。旧闭包入口在改变请求序号、清空列表或中止请求前先检查页面范围。
## 分页并发
首屏刷新会使旧续页失效,清空续页游标并释放旧分页 UI。续页由同步 ref 取得一次请求所有权,避免 React 重新渲染前的连续点击发出重复请求。接收续页时同时核对请求所有权、首屏请求序号和页面范围;切换项目、账号、视图或同范围刷新后,旧结果与旧错误均不能写入当前页面。迟到请求只能释放自己的忙碌状态。
失败保留原列表与原游标,可以重试。去重追加、每次增加 200 条展示上限、服务端总量口径沿用现有行为。
## 关联查询的完整性
原非管理员关联路径只取前 1000 个任务 ID,并拼成一次 GET。本轮改为复用已有 `loadAnnotationTaskJoin`:关联已返回任务池中的全部去重 ID,每个请求最多 50 个 ID,每组最多 4 个并发。空列表不查询无关任务。
每批 HTTP 查询各自排序后,模块按原来的 `createdAt`、`id` 降序恢复整体顺序,避免批次拼接改变任务展示顺序。此处仅补齐当前已返回任务池的关联;没有新增全库扫描,也没有改变普通任务池端点既有的返回窗口或扩大用户可见范围。
## 验证
```sh
npm run test:annotation:pools
npm run test:browser:annotation-pools
npm run test:browser:annotation-persistence
npm run test:frontend:gate
```
前两项接入 Fanyu 本地发布检查。模块测试与页面实际回调测试共 49 项,覆盖三类池、验收双阶段、1221 个关联任务、跨批整体排序、权限错误、旧闭包、元数据失败、同范围刷新、重复点击、旧响应及失败重试。
任务池浏览器测试使用真实页面、Go HTTP 和隔离 MemoryStore 的 611 条合成任务,包含 9 个场景:分页与总量、失败重试、刷新时的迟到续页、重复点击、首批之外搜索、状态筛选、迟到搜索、已审核阶段以及合成领取后的计数更新。页面自身无写请求;唯一领取由测试夹具在隔离数据中执行。不会连接 Mongo 或 BOS。
浏览器与包含 Vite 的前端门禁需串行执行,避免共用工作树依赖缓存相互干扰。保留首次并行尝试的超时和错误断言日志,不把已经完成断言但清理超时的运行算作通过。最终串行结果:49 项定向测试、9 个任务池浏览器场景、18 个标注/返工页面场景通过;TypeScript、格式、生产构建、使用已安装 Edge 的 dist 启动与 37 项发布工具测试通过。全量前端门禁为既有 13 项失败、零新增,14 项基线未修改。两条过时的页面内部查询源码检查随职责迁移改为模块接线/行为验证。独立复核的旧加载闭包和跨批排序问题均已修正并补测,复核无剩余阻断项。
最终结果与日志位于忽略目录 `local-data/verification/pool-architecture-20261021/`。
## 兼容与后续
HTTP、Mongo、审核决定、交付 JSON 和后台任务协议均未修改,不需要数据迁移;回退前端会恢复原来的加载及分页行为。布局 agent 仍只接触展示配置,不接入任务可见性、领取、审核或交付判定。
审核会话、意见草稿和正式决定已经各有现有 hook。正式决定状态机及决定完成后的页面编排已在[第四阶段](review-decision-coordination.md)收敛;意见草稿、会话与连续审核保留各自职责。独立镜像发布、JSON v4 和实际 agent 尚未实现。
## 2026-11-02:审核池全范围搜索与分页
质检与验收工作区改用独立的 `review` 读取模式:可领取、我的任务、已审核分别保存服务端游标,每页最多 200 条;切换页签复用已加载页,加载更多只读取当前池。验收将原来的两个阶段合并为一次 `stageIds` 查询,不再通过 `listAllItems` 逐页拉完整池。任务关联仍按 50 个 ID、最多 4 个并发读取;前端显示“已加载”及未加载完的 `+`,不冒充实际总量。
`GET /api/human-items` 兼容新增 `search/capture/category`。搜索在分页之前执行,支持 Capture、part、项目名称及任务身份;`Capture/part0002` 也匹配旧式 `Capture_camera_left_part0002.mp4`。输入按普通文字匹配,不执行用户提供的正则表达式。正常排序仍为稳定的 `createdAt/id` 降序,旧任务新送检不会改写导入时间,但能够通过全范围搜索及继续分页找到;不以易变的更新时间作为分页键。
Mongo 对有权威 Capture 记录的数据先筛选名称和状态,仅返回匹配候选;缺少该来源的旧记录保留原有元数据回退。查询保持 8 秒超时、200 条传输批次及取消传播,不加载工作区草稿。质检可领取候选进一步使用本请求核对的项目和供应商必要范围,复用 `b2324c19` 中的范围收缩及等价测试;共享验收、已审核历史不套用这项供应商收缩。候选仍经过原服务端实时可见性与 `canClaim` 校验,没有权限缓存或新增索引。
已审核分类沿用原有展示口径:三角色流程中,质检通过的来源任务在最终验收未通过前仍显示“待验收”,最终验收通过后才显示“已通过”。筛选在分页前按这项有效状态判断;每批只批量补充验收状态,不逐条加载下游任务正文,也不改写来源任务。`TestReviewedHistoryCategoryPaginationUsesDownstreamStatus` 覆盖 205 条混合状态历史记录、连续分页、无重复/遗漏及返回详情完整性。
搜索、状态、项目和账号变化会清空旧游标并取消旧请求;迟到回包不能覆盖新列表,续页失败保留原游标供重试。新接口返回 `filtersApplied: true`。新前端在筛选时遇到旧服务未返回该标记会提示版本暂不支持,不显示未经筛选的数据;旧客户端忽略新增字段。发布时先升级服务端,再启用前端筛选。
本地证据:`TestHumanPoolSearch*` 覆盖前方有 962 条新任务的旧 part、三种池各 611 条连续分页、供应商隔离、自审禁止和普通文字匹配;`TestHumanPoolSearchMongo*` 对照 Memory/Mongo 与 1 万条数据;`TestReviewPoolSearchBrowserReplica` 使用真实 HTTP、合成账号与真实页面验证搜索、分页、失败重试和旧回包处理。完整容量仍须独立验收。