droboticflow/docs/quality-acceptance-loading.md
2026-09-29 07:44:59 -07:00

52 lines
5.8 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-09-29)
- 最终验收页使用现有 `stageId` 查询参数,分别读取 `prepackage_acceptance` 与历史 `acceptance` 阶段,再按任务 ID 去重、创建时间倒序合并。不同响应中同一任务的版本不同时保留较新版本。任一阶段加载失败都明确报错,不把部分列表当作完整结果。
- 管理员只读取这两个阶段的 `all` 池,再从服务器已授权返回的记录中得到可领取和本人任务;普通终审员只读取两个阶段各自的 `available`、`mine` 池。组织、项目、供应商与角色权限仍由服务端校验,不新增接口或放宽权限。
- “可领取/我的任务/全部任务”在已加载列表内切换,不重新读取项目。领取响应继续即时更新归属;手动刷新仍会重新读取服务器。
- 验收页的工时统计、退回记录进入对应页签才请求,不占用首屏任务池加载。切换项目后丢弃旧项目的慢响应。
- 历史验收任务、标注任务及交付包读取路径继续保留;非“全部任务”视图仍只显示待验收交付包。没有迁移或改写客户任务、审核意见、标注 JSON,也没有改变验收提交规则。回退前端不需要回退数据。
## 验收首屏
证据目录逐页累积显示,已返回的完整切片可先播放、查看描述。未收到完整目录、缺文件或元数据检查失败时,不能通过验收;最终批准门槛未放宽。目录分页意外中止会报错,不将部分结果视为完整。
## 服务端
审核证据索引按组织、项目、HumanItem/版本、Run/父 Run、产物描述(含版本/摘要)缓存,30 秒有效,最多 16 项、约 16 MiB 编码索引。相同索引的并发请求合并为一次构建;失败、不完整识别或取消不缓存。过期、版本或产物变化重新生成。
每次请求仍重新检查账号、任务权限和产物所属范围。文件内容不缓存;打开本地文件时重新检查路径和符号链接,BOS 文件打开时重新读取存储连接。首次打开大目录仍需要一次索引生成,后续分页和文件请求复用索引。
`Server-Timing: evidence_index` 标记索引读取耗时和命中情况;`review_latency` 日志分别记录领取、质检决定和验收决定的服务端总耗时。审核写入与后续流转仍保持原有同步一致性流程,本次没有提前返回成功或改变交付状态。
## 验证
- `go test ./internal/api -run 'TestHumanEvidence|TestHumanItemEvidence|TestRunArtifactMembers' -count=1 -v`
- `go test -race ./internal/api -run '^TestHumanEvidenceCache|^TestHumanEvidenceFailed' -count=1`
- `npm run lint:web`、`npm run build:web`
- 本地 Vite:`npm run dev:web -- --host 127.0.0.1 --port 5176 --strictPort`
- `node tests/browser/acceptance-progressive-loading.mjs`(安装的 Chrome、ffmpeg;生成 1 秒合成视频)
- `node tests/browser/review-loading.mjs`
- `REVIEW_TEST_MODE=acceptance node tests/browser/review-loading.mjs`
浏览器用实际组件和应用路由、受控的慢接口,验证质检/验收领取与提交不依赖慢任务池或统计、首个验收切片先于最后一页可播放、证据齐全前批准禁用。API 测试覆盖 450 文件的分页复用、并发、过期、版本变化、权限拒绝和缓存后的符号链接替换。
### 2026-09-29 任务池优化验证
- `node tests/browser/acceptance-pool-loading.mjs`:实际应用与 API 封装,覆盖管理员/终审员、新旧阶段、任务池切换不重载、报表延迟不阻塞、跨项目慢响应隔离及历史阶段失败提示。使用本地合成响应,不调用生产写接口;可用 `BROWSER_PATH` 指定浏览器。
- 独立本地 Mongo 数据库和 API 实测:管理员/终审员分阶段任务池返回正确,无权限项目不返回记录,普通终审员访问 `all` 池返回 403。
- 验收证据渐进加载浏览器回归通过:首片可先查看,目录完整前不能通过验收。本机使用 Edge 运行原测试,仅替换测试副本的浏览器启动配置。
- 类型检查、生产构建通过;全量前端测试 623 项,609 通过、14 项既有失败,逐项名称、位置和失败断言与改动前一致,无新增失败。
- 额外 Go 权限回归发现两项当前基线失败:`TestHumanPoolsFollowAnnotatorReviewerStageOwnership` 的旧阶段角色预期,及 `TestAdminCanReassignHumanItemToEligibleWorkerOrReturnItToPool` 的测试用户缺少项目角色。`internal/`、`cmd/`、`go.mod`、`go.sum` 与改动前 HEAD 完全一致;未为本次前端优化修改这些权限规则。
本次证据保存在本机忽略目录 `local-data/verification/acceptance-loading-fix-20260929/`。这些是本地验证;本次没有部署公司集群,也没有修改客户数据。之前线上只读测得同一项目全阶段查询约 30.5 秒、15.35 MB,而限定新验收阶段查询约 190 ms、280 KB;这是当时单次接口观测,不是本次上线后的整页性能承诺。