Files
Endoleap/docs/03-edit.md

4.1 KiB
Raw Permalink Blame History

3. 一次编辑如何成立

上一章 · 目录 · 下一章

把“改标题”翻译成命令

假设当前节点有有效 target,支持对应编辑能力。标题从“想法”改为“行动”的核心接口形态是:

engine.editor.dispatch({
  type: 'element.data',
  target, // 当前元素的 { id, incarnation }
  patch: { title: '行动' },
});

这只是已取得 engine 后的命令示意。真实界面还要处理焦点、编辑租约、目标是否仍有效等问题。不要绕过命令直接修改 snapshot 中的 Map 或元素对象;它们是受保护的发布结果。

从命令到候选文档

editor.ts 的 dispatch 是同步 transaction 的便捷封装。事务内部先在候选文档上规划命令,得到 changes。规划会解析目标、检查宿主 policy、组件能力和字段规则;提交前还会对候选文档做整体校验。

Registry 在这里负责解释“这个组件允许什么”。一个元素存在,不等于它支持任意命令。未来版本和未知组件可以保留原始数据,但不能借此调用未安装的行为。

Change 描述实际发生的变化,OperationIntent 描述需要同步的逻辑意图,HistoryEntry 则组织用户可撤销的工作单元。它们有关联,却不是同一个对象。

为什么两个命令可以一起成功或一起失败

例如一个 counter 节点同时移动位置并把 count 改为负数。第一条命令可以在候选文档中成立,第二条违反 schema。事务最终拒绝时,候选文档被丢弃,原文档、历史、操作记录和通知均不应留下第一条命令的结果。

完整例子在 consumer.mjs:找到标有“非法事务”的部分,再与后面的合法事务比较。合法的移动与计数更新被组织成一个历史单元。

事务回调必须同步。异步读取和资源准备先在事务外完成,再带着仍需重新验证的目标进入事务。await 期间世界可能变化,不能持有一个可在稍后继续写的事务草稿。

发布边界里还有 runtime

事务成功后进入 publish,构造历史与操作等候选状态。engine 创建 Editor 时注入 reduceRuntime,将新操作合入 ledger,并整合相关资源任务;prepareRuntime 再检查所有权、加载和资源保留等规则。

这些准备在最终 state 赋值之前完成,因此“文档已改但待同步操作没有入账”不应成为一次成功提交的状态。准备钩子不做网络 I/O;如果它们偷偷产生外部写入,丢弃候选根也无法撤销外部副作用。

订阅者随后观察已发布状态,更新页面或调度后续工作。监听器发生异常不能把已经提交的文档倒回去。

撤销为什么不是恢复整个旧快照

撤销根据历史变化与当前状态执行校验,再发布补偿意图。它必须保留期间到来的有效服务端资源确认等运行事实。如果只是把整个状态替换成编辑前的快照,这些事实会丢失。

同字段冲突时撤销可能拒绝,并保持历史栈不动。删除后撤销恢复元素会产生新的 incarnation,因此此前捕获的 target 继续失效。一次无实际变化的提交可以返回 applied,但不产生新的 operation;applied 不代表必然发生写入。

跟踪任务

先跟踪 dispatch → transaction → plan → publish,再到 engine.ts 找 createEditor 的 reduceRuntime 和 prepareRuntime。标出候选状态在哪里变成发布状态。

在 core.test.mjs 阅读标题含 rejected second command、same-field conflict、async transactions 的测试。分别写出它们保护的事实。

自检

dispatch() 返回 applied,是否意味着服务器已保存?

不是。它说明本地命令已成功处理;还需区分有无实际变化、本地可靠持久化是否完成,以及操作是否收到并协调了服务器回执。下一章看页面为什么能先响应,第 5 章再看后续可靠性。