挑战一：完善 json-joy，自主实现 Undo/Redo 引擎#

痛点：对于一个专业的低代码编辑器，撤销/重做（Undo/Redo）是绝对的刚需。但在当时，json-joy 原生版本根本不支持 Undo/Redo 功能！ 在协同环境下，如果你只是单纯地把整个树的状态替换为一分钟前的快照，那不仅会撤销你自己的操作，还会把你同事在这过去一分钟里写的心血全部覆盖掉。

解法：基于差异的反向补丁生成器 (reverseLocalPatch.ts) 既然官方不支持，我们就自己造！我们扩展了原生的操作，设计了一个包含了非常详尽上下文的自定义 Diff 接口：

1
// 我们自定义的 Diff 数据结构，包含了逆向操作所需的全部元信息
2
interface DiffItem {
3
  operation: 'add' | 'update' | 'delete' | 'move' | 'copy';
4
  newValue: any;
5
  oldValue?: any;
6
  pathComponents: PathComponent[]; // 精准的目标路径，如 ['components', 'button_1', 'style']
7
}

当用户按下 Cmd+Z 触发 Undo 时，我们不会退回旧状态，而是在当前最新状态下，动态计算并派发一个“反向补丁 (Reverse Patch)”。在 reverseLocalPatch.ts 的深层逻辑中，每一个操作都有绝对的数学逆运算：

1
// 非常简化的核心逆向路由逻辑演示
2
function reverseDiffItem(item: DiffItem): DiffItem {
3
  switch (item.operation) {
4
    case 'add':
5
      // 别人/自己加的内容，逆向操作就是把它删掉
6
      return { ...item, operation: 'delete', newValue: undefined, oldValue: item.newValue };
7
    case 'delete':
8
      // 删掉的内容，利用缓存的 oldValue 原样复原
9
      return { ...item, operation: 'add', newValue: item.oldValue, oldValue: undefined };
10
    case 'update':
11
      // 修改属性，直接将新旧值互换
12
      return { ...item, operation: 'update', newValue: item.oldValue, oldValue: item.newValue };
13
    // ... move 与 copy 的非常复杂的逆向拓扑运算
14
  }
15
}

高光时刻：在真正执行反转应用之前，为了防止别人刚刚把这个容器删了，你现在却要“撤销修改里面按钮的颜色”引发底层报错，我们还加入了一个 沙盒模拟校验 (Dry-run)。 底层调用了 executeCrdtNodeUpdateOptimized，在当前被别人改得“发生变更”的 CRDT 树上虚拟执行一次反向操作，如果抛出校验异常，说明该历史操作在当前时空已经不合法，系统会直接丢弃这个 Undo 动作；如果校验通过，逆向 Diff 最终会被转化为正常的 CRDT Patch 广播出去，完美攻克了多人时序下的状态回溯难题。

挑战二：业务逻辑正确性拦截 (The Firewall)#

痛点：json-joy (或者任何 CRDT) 只能保证数学意义上 JSON 数据结构的最终一致性，但它完全不懂你的业务正确性。 举个极端的例子：用户 A 往 List 容器里放了一个 Button 组件，触发了 Button 创建的 Patch；与此同时，用户 B 把整个 List 容器给删除了。 CRDT 完美合并了这两个操作，最终结果是：数据库里多出了一个幽灵 Button，但它根本没有可以挂载的父容器！这种脏数据一旦渲染，直接导致 React 运行时白屏崩溃。

解法：合并后的 ztype 业务防火墙 我们在每次接收并应用远端 Patch 后，强制接入了底层业务类型校验器（基于 ztype），像一道防火墙一样严格拦截渲染层：

flowchart TD
    Receive["接收其他客户端的 Patch"] --> Merge["json-joy 底层合并 (无脑合并)"]
    Merge --> Extract["提取合并后的 Schema 关联数据"]
    Extract --> Validate{"ztype 业务正确性校验\n(如: 容器存在吗? 循环嵌套了吗?)"}
    
    Validate -->|"校验通过"| UpdateUI["向下流转: 派发 Diff 刷新 MobX 与 UI"]
    Validate -->|"校验失败 (产生脏数据)"| Revert["触发静默回退 (Silent Revert)"]
    Revert --> GenerateReverse["将错误节点回退，生成修正 Patch"]
    GenerateReverse --> SendBack["将修正 Patch 广播给所有人，强行修复该错误"]

在核心同步逻辑中，任何数据进入画布渲染前，都会进行拓扑图关联检查。如果发现合并出来的 JSON 违反了低代码业务的逻辑约束，系统会进行静默回退 (Silent Revert)。我们宁可让那个非法操作“无效”，也绝对不允许脏数据污染并打断当前用户的编辑心流。

挑战三：双状态树的平滑过渡 (Dual-Store Architecture)#

痛点：面对有着数百万行遗留代码的大型编辑器，我们不可能停下业务发版，花半年时间把所有依赖 MobX 状态响应式的组件全部重写为订阅 json-joy。

解法：核心模型与台前镜像 为了在不重构老组件的前提下接入协同，我们构建了一个名为“双状态树（Dual-Store）”的过渡期架构：

sequenceDiagram
    participant UI as React UI (依赖 MobX)
    participant CrdtHelper as @crdt-helper (同步网关)
    participant CRDT as jsonJoyModel (Single Source of Truth)
    participant Server as WebSocket 服务端
    
    %% 本地操作管线
    Note over UI,Server: 本地数据变异 (Local Action)
    UI->>CrdtHelper: 1. 操作触发产生本地 Diff
    CrdtHelper->>CRDT: 2. applyLocalCrdtDiff (校验后打入核心模型)
    CRDT-->>CrdtHelper: 3. 产出二进制 Patch
    CrdtHelper->>Server: 4. 发送 Patch 给其他客户端
    CrdtHelper->>UI: 5. updateMobxStore (同步回 UI 镜像)
    
    %% 远端同步管线
    Note over UI,Server: 远端补丁应用 (Remote Patch)
    Server->>CrdtHelper: A. 收到别人发来的大型 Patch
    CrdtHelper->>CRDT: B. 优先静默合并到 CRDT 模型
    CRDT-->>CrdtHelper: C. generateDiff: 深度对比新旧 Schema
    CrdtHelper->>UI: D. 仅将极细粒度 Diff 派发给 MobX

1. Single Source of Truth：jsonJoyModel 成为了真正的幕后单一数据源，所有本地操作、网络同步、冲突消解，全都在它内部原子化完成。
2. MobX 作为投影镜像：原有的 MobX Store 被降级为视图层的一个镜像。当收到远端全量的 CRDT 更新时，为了防止 MobX 触发全屏海量 Re-render 卡死，底层会先执行 generateDiff 计算出极小粒度的差异（例如仅仅是一个子节点的 insert），然后只将这些细微的变动派发给 MobX 增量更新。

旧组件完全感知不到底层换了引擎，依然欢快地吃着 MobX 的响应式福利，实现了架构切换的“零阵痛”。

挑战四：抽象与封装——@functorz/crdt-helper 的诞生与实战#

痛点：json-joy 提供的 API 非常底层（如 api.find(), ObjNode, ArrNode, api.flush()），如果让 zed（前端业务项目）直接操作这些底层 API，会导致业务逻辑与 CRDT 引擎深度耦合。一旦未来需要更换协同引擎，或者在 Node.js 网关层复用逻辑，重构成本将是灾难性的。

解法：独立封装 @functorz/crdt-helper 桥接层 为了实现业务与底层协同引擎的解耦，我们抽离出了一个独立的 npm 包 @functorz/crdt-helper。它扮演了“适配层”和“协调者”的角色：

1. API 升维：将 json-joy 晦涩的节点操作，封装为面向业务的 executeCrdtNodeUpdateAndTransformDiff 等高级方法。
2. 双向数据流同步：它不仅负责把业务的 Diff 写入 CRDT 模型，还负责将 CRDT 的变化反向解析，并通过回调（如 updateMobxStore）精准更新 MobX 状态树。
3. 多端复用：作为纯逻辑包，它同时运行在 zed 前端和 Node.js 协同网关中，保证了双端对 Patch 解析逻辑的绝对一致。

1
const diff = {
2
  __typename: 'DiffItem',
3
  operation: 'update',
4
  pathComponents: ['components', 'button_1', 'style', 'color'],
5
  newValue: '#FF0000'
6
};

1
const result = Crdt.executeCrdtNodeUpdateAndTransformDiff(
2
  [diff], // 业务 Diff
3
  schemaStore.jsonJoyModel, // 核心模型：CRDT 实例
4
  coreStore, // 旧的 Schema 状态
5
  updateMobxStore, // 非常关键的回调：用于同步 MobX
6
);

1
// @functorz/crdt-helper 内部逻辑简写
2
export const executeCrdtNodeUpdateAndTransformDiff = (...) => {
3
  // 1. 寻址并修改底层 CRDT 节点
4
  const operableNode = model.api.find(['components', 'button_1', 'style']);
5
  operableNode.set({ color: '#FF0000' });
6

7
  // 2. 触发回调，将极细粒度的变更同步给 MobX 镜像
8
  const crdtDiffs = transformLocalDiffsToCrdtFormat([item], model, oldSchema, updateMobxStore);
9

10
  // 3. 冲刷出二进制补丁，并转为 Base64 准备广播
11
  const patch = model.api.flush();
12
  return { patchBase64: convertPatchToBase64(patch), diffsFromCrdt: crdtDiffs };
13
};

1
export function updateMobxStore(node: any, diff: DiffItem) {
2
  const lastKey = diff.pathComponents.at(-1)?.key; // 'color'
3
  node[lastKey] = diff.newValue; // 直接修改 MobX 对象，触发 React 局部重渲染
4
}

1
export const buildSchema = (json: any, pathComponents: DiffPathComponent[]): any => {
2
  for (const nodeMatch of ALL_NODE_MATCH) {
3
    if (isFullMatch(nodeMatch)) {
4
      if (nodeMatch.valueMatch(json)) {
5
        return s.con(json); // 👈 核心优化：直接作为常量节点，停止递归！
6
      }
7
    } else if (isPartialMatch(nodeMatch)) {
8
      if (nodeMatch.pathMatch(pathComponents.slice(0, -1))) {
9
        const lastKey = pathComponents.at(-1)?.key ?? '';
10
        if (nodeMatch.isConstKey(lastKey)) {
11
          return s.con(json); // 👈 核心优化：特定 Key 直接作为常量节点
12
        }
13
      }
14
    }
15
  }
16

17
  // ... 否则继续递归构建 s.arr 或 s.str
18
};

挑战五：CRDT 时代的时光机难题 (Undo/Redo 隔离)#

痛点：传统的单机编辑器中，撤销/重做（Undo/Redo）非常简单：只要维护一个状态快照（Snapshot）数组，按下 Cmd+Z 时指针后退一步即可。 但在实时协同的 CRDT 环境下，这种“粗暴的回退”是灾难性的。假设当前状态是 S1，用户 A 把按钮改成了红色（状态变为 S2），紧接着用户 B 把标题改成了“你好”（状态变为 S3）。 如果此时用户 A 按下撤销，他期望的是**“按钮变回原来的颜色”**，但如果简单地把全局状态回退到 S1，用户 B 辛辛苦苦敲的“你好”也会跟着一起被无辜抹除！

如何实现只撤销“自己”的操作？

解法：Session 隔离与反向 Patch 的精准对冲

在基于 json-joy 的新架构中，我们放弃了“状态快照栈”，转而实现了一个**“操作语义栈 (Action Stack)”**。

1. Session ID 染色： 每个客户端在初始化时都会生成一个独一无二的 SessionID（通常是一个随机的 UUID）。当用户在本地进行任何操作（如修改颜色）生成 Patch 时，底层引擎会自动将这个 SessionID 注入到该操作的元数据（Metadata）中。

2. 本地历史栈隔离： 客户端的 Undo 栈里，不再存全局的 JSON 树，而是只存带有自己 SessionID 的反向补丁 (Reverse Patch)。当用户 A 把颜色从蓝色改成红色时，他的本地历史栈会被推入一个记录：“将目标路径的颜色改回蓝色”。

3. 时空对冲 (Chronological Hedging)： 当用户 A 按下 Cmd+Z 时，系统从本地历史栈弹出那个“改回蓝色”的反向补丁，并作为一个全新的、发生在当前时间点的前进操作 (Forward Action) 执行。

   最绝妙的地方在于，CRDT 引擎（json-joy）在应用这个反向补丁时，依然遵循 LWW（Last-Write-Wins，最后写入胜出）或树的拓扑合并规则。它会去检查目标节点当前的逻辑时钟（Logical Clock）。如果这个按钮在用户 A 改红之后，又被用户 C 改成了绿色，那么用户 A 的“撤销为蓝色”补丁在应用时，会基于时间戳或因果关系进行合并，而不会破坏整个数据结构的完整性，也绝对不会波及到用户 B 修改的标题。

通过这种“以进为退”的对冲机制，我们在没有修改 json-joy 底层核心算法的前提下，完美实现了协同场景下极其精准的、属于用户自己的非线性 Undo/Redo。