# 5. 本地保存、网络同步与恢复 [上一章](04-view.md) · [目录](README.md) · [下一章](06-development.md) ## 三种“成功” 用户改完标题,页面立即显示“行动”。此时只知道本地发布成功。之后还需要可靠保存恢复材料,再推动网络请求,最后解释服务器结果。 | 阶段 | 已知事实 | 尚不能推断 | | --- | --- | --- | | 本地发布 | 当前内存文档及关联状态已更新 | 浏览器崩溃后可恢复 | | 本地持久化 | 对应恢复材料已被存储端口确认 | 服务端已经采用修改 | | 服务器结果协调完成 | 回执已被解释并纳入本地状态 | 其他尚未完成操作也已同步 | ## ledger 为什么与文档一起推进 ledger 记录逻辑操作、依赖和请求事实。scheduler 根据这些事实判断谁能发送,处理冻结请求、占用、重试和状态查询。它不会通过比较 React 组件状态来猜测需要保存什么。 [engine.ts](../src/lib/canvas-runtime/engine.ts) 将本地提交转换为 ledger 更新,然后把 ledger 读取、状态更新、可靠保存和具体请求执行注入 [scheduler.ts](../src/lib/canvas-runtime/scheduler.ts)。这把“决定发送什么”和“具体怎么访问 Foundry”分开。 请求冻结后,重试必须保持原请求身份与内容。发送之前要可靠保存相关请求身份和前置状态,否则进程在服务端执行后崩溃,重启时可能无法知道自己已经发过什么。 ## 请求走到哪里 浏览器服务适配器通过同源 transport 访问 Next 的 [Foundry route handler](../src/app/api/foundry/[...path]/route.ts),由服务端代理请求上游。浏览器持 HttpOnly 会话 Cookie;代理在服务端转换上游认证,并限制路径、请求头、大小和超时。 [canvas-service/foundry.ts](../src/lib/canvas-service/foundry.ts) 处理 canonical 模型、操作协议与回执语义。代理负责传输边界,不能替代领域 schema 校验。冻结写入保留原字节,避免在中转时重编码而破坏请求身份。 认证到期续期由后端会话合同和 [session-cookie.ts](../src/lib/session-cookie.ts) 等代理逻辑协作完成。前端不能单靠延长浏览器 Cookie 来复活服务器已失效的会话。 ## 请求发出后断网,为什么不能直接重做 假设服务器已执行“想法 → 行动”,响应在途中丢失。客户端看到的网络错误不证明操作未执行。若立刻生成新请求,复制、创建等操作可能重复发生。 因此 runtime 保留原冻结请求与不确定状态,沿原身份查询或重试。`accepted` 也不等于最终应用并协调完成。具体状态需要服务协议解释,不能把 HTTP 成功统一变成“保存完成”。 ## ACK 如何避免盖掉后续编辑 客户端收到第一次标题修改的确认时,用户可能已继续输入。runtime 维护 acknowledged 基线与当前 working 文档,根据回执推进已确认状态,再协调尚未解决的本地操作。不能把服务端返回的文档直接覆盖到界面上,否则后一次编辑会丢失。 [reconcile.ts](../src/lib/canvas-runtime/reconcile.ts) 提供相关协调与重放逻辑。若服务端已应用,但本地无法安全协调,engine 保留回执和冲突材料,阻塞相关流程并报告恢复需求;它不会把失败候选中的一半状态当成成功发布。 ## 刷新后如何接续 浏览器 storage 适配器使用 IndexedDB 等能力保存恢复记录,并配合 leader 所有权控制本地写入。重新打开项目先解释恢复材料,再处理未解决请求。恢复需要的不只是最终 Document,还包括历史、ledger、已确认基线及相关资源和版本证据。 [storage-port.ts](../src/lib/canvas-runtime/storage-port.ts) 定义端口合同;[storage.ts](../src/lib/canvas-runtime/storage.ts) 实现浏览器侧存储;[recovery.ts](../src/lib/canvas-runtime/recovery.ts) 负责恢复编解码。内存示例能证明合同接线,但不能证明跨进程崩溃持久性。 ## 跟踪任务 在 engine 中找到 `createScheduler`,标出 `persistThrough`、执行请求与协调结果的连接。到 [engine.test.mjs](../tests/headless/engine.test.mjs)、[durability.test.mjs](../tests/headless/durability.test.mjs)、[crash-windows.test.mjs](../tests/headless/crash-windows.test.mjs) 中,分别找普通编辑、发送持久屏障、崩溃窗口相关断言。 用自己的话写出“本地提交 → 恢复材料可靠保存 → 请求发送 → 结果解释 → ACK/working 协调”。这是职责时序;具体 I/O 可以批处理或重入调度,不能把这句话当作每次都只发生一次的函数调用栈。 ## 自检 **为什么刷新后不只重新 GET 服务端模型?** 因为尚未确认的本地编辑、结果未知的请求和可恢复任务可能只存在本地。直接丢掉恢复记录会丢失用户工作,也可能让已执行的操作再次执行。