droboticflow/docs/architecture/review-draft-persistence.md

8.2 KiB
Raw Permalink Blame History

审核草稿保存协议与编辑保留

2026-10-21,第五阶段。本轮拆出单条审核草稿操作的 HTTP 保存协议,补齐编辑队列与复审核对结论的保存衔接;没有部署公司环境。

职责

src/lib/review-draft-persistence.js 提供 createReviewDraftPersistence(...).write(...),输入不可变的待确认操作、当前归属检查、会话头读取和已有的落盘证据判定,返回 applied、blocked 或 stale 结果。

它集中处理:未知结果的草稿与回执查询、沿用原操作号/载荷的显式重试、PUT 后读回、版本冲突后的读回、结果版本变化,以及哪些失败足以解除待确认保护。生产使用原有 HTTP wrapper,模块测试使用可控延迟和错误 adapter。模块不直接修改 React 状态,不负责编辑队列或焦点,也不自动重发写请求。

useReviewDraft 保留意见目标、文字编辑、旧多条意见整理、删除确认、串行队列、入队载荷、重定基线、播放定位、8 秒空闲保存调度及展示状态。它应用协议返回的结果,继续使用原来的 operationId / resultVersion / version 和服务器 CAS。

本轮修复

旧请求与输入保留

  • 未知结果查询返回 404 后,必须再次检查任务/结果范围、会话代次和挂载状态,才能取会话头并发 PUT。旧查询不能借用新会话发送旧操作。
  • 任务范围采用独立身份,离开后返回相同范围不复活旧回调;saveAll 和 prepareSubmit 每个异步阶段都检查原生命周期。挂载清理覆盖禁用分支,停止旧焦点、位置事件与保存回调。
  • 被审结果变化会解除不能再应用的旧 pending,但保留后来输入或排队的文字;只有没有更新的本地文本时才恢复旧快照。
  • PUT 明确被拒与 PUT 成功后读回失败分开分类。读回 403、网络失败或无充分证据时不能推断 PUT 没有效果;保留原操作等待核对。
  • 新操作在取会话头前就失败时,没有未知写入需要保护,可以解除该 pending 并保留编辑;已有未知操作仍必须读回。
  • 每个 flush 仍只释放自己的 busy 标记。代次变化不使旧请求卡死 busy,也不让旧请求释放新的在途保存。

复审核对结论

仅修改“已解决/仍有问题”和说明也立即算未保存,参与页面离开检查。saveAll / 离开保护中的保存同时处理文字与结论;明确放弃会恢复已保存结论。正式决定前继续要求“仍有问题”填写说明,服务器仍是最终校验者。

结论比较按服务器的 ID/说明去空白、空说明可省略的语义处理;保留输入次序、不合并不同判断、不重写本地正文。避免服务器省略空 note 或裁剪说明空白后,页面永远判为未保存。

刷新读取和同结果的新会话初始化,保留尚未保存的本地结论;没有本地差异时采纳服务器值。即使本地选择改回旧基线,也会比较在途载荷,保留发出请求后的改判,不用“等于旧基线”推断用户没有新操作。读取期间仍允许继续输入当前任务的文字。不同任务或不同被审结果不会复用旧结论。

兼容性

没有改变 HTTP、Mongo、服务器操作回执、审核权限、原始标注、冻结返工基线或交付 JSON。没有新增依赖或浏览器存储格式。旧多条意见、历史整体意见与原有人工确认路径保留;ADR0008 的旧问题延续规则和 ADR0009 的停用整体意见继续有效。

后台已经在途的草稿操作沿用原操作号和载荷,先查询再决定是否重试,不把新文字塞入旧操作。无需数据迁移;前端回退会恢复原来的编辑保留和离开检查行为,已经保存的草稿仍按原协议读取。

验证

npm run test:review:drafts
npm run test:browser:review-drafts
npm run test:frontend:gate

前两项接入 Fanyu 本地发布检查;服务器定向检查补入草稿及复审核对结论测试。包含 Vite 的测试串行执行。

  • 52 项定向测试通过,覆盖单操作保存/读回、未知结果、回执终态、404 后失权、冲突、PUT 与读回错误区分、结论比较、空闲调度及历史兼容接线。
  • 质检、验收各 14 个真实 HTTP + React hook 场景通过,共 28 个,全部使用隔离 MemoryStore。覆盖结论离开保护、明确放弃、只保存结论、服务器省略/裁剪说明、旧成功或失败响应后的新输入、刷新期间输入、刷新保留结论、丢响应无重复 PUT、冲突后的明确重试、代次变化及卸载。
  • 代次变化在浏览器夹具中模拟客户端收到新会话快照;实际服务器 takeover fencing、进程崩溃恢复、草稿目标/来源隔离及结论冻结由原有定向 Go 回归验证。
  • 正式决定的真实回执及两角色失败/连续审查回归通过;完整标注/返工 18 个场景在单独复跑中通过;首次运行在 E 面板第三次场景等待冲突清单时超时,无页面异常,触发条件尚未定位,保留为测试不稳定性待查,不能把这次失败计为通过。
  • 全量前端门禁仍为已有 13 项失败、零新增,14 项基线未修改。一条旧测试硬匹配原内联错误前缀的断言已随协议提取改为结果接线,并由真实行为回归补强。
  • TypeScript、格式、生产构建、已安装 Edge 的 dist 启动和 37 项发布工具测试通过。

首次验收浏览器夹具误用了质检的切片/来源身份,被现有服务器 400 拒绝;已改用验收聚合来源 ID 和相对时间,再次完整通过。新增代次变更夹具也改为等待真实 GET 完成后再保存,避免把加载未结束时的拒绝保存当作业务失败。失败尝试及最终记录保存在忽略目录 local-data/verification/review-draft-architecture-20261021/。夹具只允许当前合成草稿的 PUT,禁止正式决定等其他写入,不连接客户 Mongo、BOS 或公司服务。

后续

本轮只提取单操作保存协议,编辑队列与导航仍在 hook 中,没有把整个 hook 搬进新类。后续可按可验证的业务流继续收敛队列与展示职责;布局 agent 继续只使用展示配置,不接入保存或审核判定。独立镜像、实际 agent 与生产发布均不在本轮范围内。

2026-10-22 本轮批注集中查看

依据平台调优中王子予 2026-10-21 17:53 的消息与截图,恢复右侧全部批注列表,保留上方当前切片/动作/时间点的编辑卡片。列表直接读取当前任务、当前审查轮次已加载的草稿,不随当前切片筛掉其他批注,也不新增查询、轮询或后台统计。未保存文字继续由原编辑器与未保存提示处理,不把它伪装成已经保存的批注。

列表显示切片、动作、时间点批注的位置与正文,点击复用原意见选择和定位流程;验收使用原有来源到可见切片的映射,避免不同来源使用相同切片 ID 时定位串源。只读时仍可回看,编辑和保存继续受已有会话与服务端校验保护。切换条目时已有未保存文字按原 park/保存协调处理,不新增写入路径;无编辑变化的列表定位不发送保存。

ADR0008 的未解决退回基线和 ADR0009 的隐藏整体意见保持不变。列表不复活历史已解决意见,不改变分类、原标注、审核结论、接口、数据库或交付 JSON,无需迁移。

验证在真实 Go HTTP + 隔离 MemoryStore 中执行,质检与验收共 34 场景通过,包括跨切片/来源同时展示、定位、只读、单条清除后的刷新和其他批注保留,以及原有丢响应、版本冲突、新输入保留与代次切换。测试生成文件曾触发 Vite 热刷新;现将夹具的 local-data 排除出监听,失败日志保留,重跑通过。另一次夹具遗漏查看控制器的 focus 实现已补齐,不作为产品缺陷。

当前优化版的 168 项保存/任务池/正式决定/草稿定向测试、19 个完整标注浏览器场景、9 个任务池场景、正式决定及权限回归通过。全量前端仍为 13 项原有失败,基线 14 项未修改。证据保存在本工作树忽略目录 local-data/verification/wangziyu-review-list-20261021/。

本轮只在个人分支本地验证,尚未部署。