Flow Diagram：让 DocumentStore 统一拥有读写、revision、rollback 与通知

[suntianc]

Parent

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

Blocked by

• Flow Diagram：明确外部写入一致性保证并消除 compare→rename 覆盖窗口 #239：先明确外部写入一致性保证与版本契约。

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

来源

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

当前缺口

FlowDiagramDocumentStore 的公开接口当前只有 saveDocument()。其余一致性职责仍散落：

• flow-diagram-service.ts 直接持有 FlowDiagramRevisionStore，自行执行 record / peekLatest / consumeLatest；
• service 直接调用多个低层原子写 helper，编排 edit 失败恢复与 rollback；
• read/get/export 仍各自读取文件；
• 变更通知由 store 与 service 分别触发；
• 三个原子写函数重复临时文件创建、写入和清理逻辑。

这不满足 #200 的核心验收：“文档存储是 .excalidraw 一致性规则的唯一拥有者；service 只保留动作解析与结果适配”。下一个 revision / rollback / publish bug 仍需要跨 Store 和 service 修改。

目标设计

建立窄而完整的主进程 Store 接口。最终签名以 #239 的版本契约为准，但能力至少覆盖：

• 读取文档内容及一致性版本；
• 创建文档；
• 基于预期版本保存完整文档；
• 基于预期版本执行 Agent 增量 edit，并在成功发布前记录 revision；
• rollback 到最近一次适用 revision；
• 为 export 提供一致的当前文档快照；
• 在成功发布后统一发送文件变更通知。

revision store 可以保留为内部实现文件，但不得继续由 flow-diagram-service.ts 直接编排。

实现范围

Store

• 吸收 revision record / consume / latest 检查和失败恢复。
• 吸收 create/edit/rollback 所需的文件读取、场景校验、发布和删除逻辑。
• 统一成功发布后的通知时机，失败或冲突不发送成功通知。
• 将临时文件创建、权限、写入、fsync、close、清理抽为单一内部原语；各操作只保留不同的条件发布策略。
• 路径限域与场景校验保持在 Store 写边界。

Service

保留：

• manage_flow_diagram action 参数解析；
• edit operation 到候选 scene 的领域变换；
• 澄清/错误结果映射；
• artifact / export 展示数据编排。

删除：

• 对 revision store 的直接依赖；
• 对低层原子文件 helper 的直接调用；
• 重复的冲突恢复与通知编排。

测试迁移

主测试面移到 Store，使用真实临时目录，至少覆盖：

1. create 不覆盖已有文件；
2. edit 成功记录 revision；
3. edit 发布失败时 revision 不残留，原文档保持；
4. rollback 只应用于匹配的最新 Agent revision；
5. rollback 失败恢复原状态；
6. export/read 取得一致快照；
7. 成功时恰好一次通知，失败/冲突零通知；
8. 写入失败无临时文件残留；
9. Flow Diagram：明确外部写入一致性保证并消除 compare→rename 覆盖窗口 #239 规定的一致性场景。

Service 测试只保留 action → Store 调用与公开结果/错误码契约，不重复测试存储内部步骤。

验收标准

• flow-diagram-service.ts 不再导入 revision store 或低层原子写 helper。
• revision、rollback、版本校验和通知只有 Store 一个拥有者。
• 三份临时文件写入样板收敛为一个内部原语。
• manage_flow_diagram 动作、参数、结果和错误码保持兼容。
• ADR-0071 / ADR-0072 的隔离历史行为不变。
• flow-diagram 全簇测试、pnpm run typecheck、pnpm run build 通过。

非目标

• 不修改 renderer 状态机；renderer 迁移由后续子 Issue 完成。
• 不增加版本浏览器或手动 rollback UI。
• 不改变 Excalidraw 格式或 export 渲染桥。
• 不将其他文件类型迁入该 Store。

[suntianc]

已在 #245 完成实现并推送；Ubuntu、macOS、Windows CI 均通过。