Flow Diagram：renderer 改用版本化 Store API，删除手写保存与 reload 协调 #241

Parent

• Architecture review 02 — Deepen the Editable Flow Diagram consistency module #200

Blocked by

• Flow Diagram：让 DocumentStore 统一拥有读写、revision、rollback 与通知 #240：DocumentStore 必须先成为读写、revision、rollback 与通知的唯一拥有者。

阻塞解除后，将本票从 needs-info 调整为 ready-for-agent。

来源

2026-07-28 对 #200 落地代码的 Spec review。

当前缺口

FlowDiagramEditor.tsx 虽已把 autosave 写入迁到 flow-diagram:save-document，但仍保留一整套 renderer 侧一致性实现：

• saveQueueRef / lastQueuedContentRef / queuedDiskContentRef；
• lastDiskContentRef 磁盘镜像；
• externalReloadVersionRef / externalReloadPromiseRef；
• 外部通知后的手写排队、二次 fs.readFile、pending preservation 与 reload 合并。

这与 #200 的目标不符：renderer 应只拥有 UX 状态和防抖节奏，写排序、版本判定与一致快照应由主进程 Store 负责。

目标行为

编辑器只保留：

• saved / dirty / saving / error 可见状态；
• autosave debounce；
• 当前未保存画布内容；
• 冲突横幅与“恢复我的版本 / 丢弃我的版本”；
• Excalidraw 原生 undo/redo；
• 关闭 tab / 切换 Project 前的 flush 入口。

主进程 Store API 提供：

• 初始 content + version；
• save(content, expectedVersion)；
• 冲突时 currentContent + currentVersion；
• 版本化变更通知，供多个打开表面刷新。

具体版本类型以 #239/#240 的结论为准，放在 src/shared/，不得在 renderer 和 main 分别复制。

实现要求

• 删除 renderer 的 Promise 保存队列；同文档写入顺序由 Store 保证。
• 删除 renderer 的磁盘内容镜像，只持有 Store 返回的 opaque version。
• 删除 external reload promise 合并逻辑和通用 fs.readFile 二次读取。
• Store 通知自己的成功 autosave 时，不得被误判为外部冲突。
• 外部/Agent 变更到达时：
  • 无本地未保存改动：刷新到最新文档；
  • 有本地未保存改动：保留本地内容并显示冲突，不静默覆盖；
  • 多次通知合并到最新版本，不回退。
• Cmd/Ctrl+S、tab flush 和组件卸载 flush 保持现有用户行为。
• preload 只暴露最小、类型化的 Flow Diagram API；通用文本编辑器不受影响。

测试

Testing Library 测试聚焦用户可见行为，不断言 ref 数量或内部函数调用顺序：

1. autosave 使用加载时版本并成功进入 saved；
2. 连续编辑最终保存最新内容，不依赖 renderer Promise queue；
3. Agent 更新且本地干净时刷新；
4. Agent 更新且本地 dirty 时显示冲突并保留本地内容；
5. 冲突响应直接采用 currentContent/currentVersion，不额外走通用 fs.readFile；
6. 恢复我的版本以最新冲突版本为新基线；
7. 丢弃我的版本回到 Store 当前内容；
8. flush 在切 tab/切 Project 前等待主进程确认；
9. notification 顺序颠倒时不回退到旧版本。

验收标准

• FlowDiagramEditor.tsx 不再包含 saveQueueRef、磁盘内容镜像或 external reload promise。
• renderer 不再用通用 fs.readFile/writeFile 参与 .excalidraw 一致性流程。
• 并发/冲突时用户未保存内容不丢失。
• 多表面变更通知按版本单调前进。
• main/preload/renderer 共享契约通过 typecheck。
• 相关 renderer 测试、flow-diagram 测试、pnpm run build 全部通过。

非目标

• 不重写 Excalidraw adapter 或画布渲染。
• 不修改通用 EditorPane 保存行为。
• 不增加手动 revision 浏览 UI。
• 不改变冲突横幅的产品文案与操作，除非版本契约要求补充可理解的信息并同步中英文 i18n。