Application Layer: 业务事件（光标、选区、撤锈栈）
    ↓
Sync Layer:       CRDT 状态向量、增量更新、快照请求/响应
    ↓
Transport Layer:  WebSocket / WebRTC DataChannel / HTTP Long-polling
    ↓
Reliability:      ACK + 重传、乱序缓冲、流控

Canvas 层（底层）：图元、连线、网格、背景
Overlay 层（中层）：光标、选框、对齐参考线、标尺
UI 层（顶层）：工具栏、属性面板、协作者头像

# 同步延迟 P95 < 150ms
histogram_quantile(0.95, rate(sync_latency_bucket[5m]))

# 冲突率（并发操作导致语义合并的比例）< 2%
rate(conflict_resolved_total[5m]) / rate(operations_total[5m])

# 离线数据未同步量
offline_pending_operations{client=~".*"}

# 渲染帧率
avg(rate(canvas_frame_duration_seconds_bucket[1m]))

// packages/crdt-core/src/id.ts
export interface LamportID {
  clock: number;      // 逻辑时钟
  clientId: string;   // 客户端唯一标识 (UUIDv4 或哈希)
  seq: number;        // 同一时钟下的序列号，解决并发生成冲突
}

export class IDGenerator {
  private clock = 0;
  private seq = 0;
  private readonly clientId: string;

  constructor(clientId: string) {
    this.clientId = clientId;
  }

  // 事件发生前调用，保证因果序
  tick(receivedClock?: number): void {
    this.clock = Math.max(this.clock, receivedClock ?? 0) + 1;
    this.seq = 0;
  }

  next(): LamportID {
    return { clock: this.clock, clientId: this.clientId, seq: this.seq++ };
  }

  // 总序比较：先比 clock，再比 clientId (字典序)，最后比 seq
  static compare(a: LamportID, b: LamportID): number {
    if (a.clock !== b.clock) return a.clock - b.clock;
    if (a.clientId !== b.clientId) return a.clientId.localeCompare(b.clientId);
    return a.seq - b.seq;
  }

  static toString(id: LamportID): string {
    return `${id.clock}-${id.clientId}-${id.seq}`;
  }
}

// packages/crdt-core/src/sequence.ts
interface SeqNode<T> {
  id: LamportID;        // 全局唯一 ID
  value: T;             // 字符 / 图元 ID / 图层 ID
  originLeft: LamportID | null; // 插入时的左邻居 ID (原始意图)
  originRight: LamportID | null; // 插入时的右邻居 ID (优化: 双向锚定)
  deleted: boolean;     // GC 标记
  // 运行时缓存字段 (不参与序列化)
  _prev?: SeqNode<T>;
  _next?: SeqNode<T>;
}

export class RGASequence<T> {
  private nodes = new Map<string, SeqNode<T>>(); // key: ID.toString()
  private head: SeqNode<T> | null = null;        // 虚拟头节点
  private tail: SeqNode<T> | null = null;        // 虚拟尾节点

  // 本地插入：记录意图锚点
  insert(value: T, leftId: LamportID | null, rightId: LamportID | null): LamportID {
    const id = this.idGen.next();
    const node: SeqNode<T> = { id, value, originLeft: leftId, originRight: rightId, deleted: false };
    this.nodes.set(IDGenerator.toString(id), node);
    this.integrate(node); // 关键：按全序位置编织进双向链表
    return id;
  }

  // 远程操作集成：幂等、可乱序调用
  integrate(node: SeqNode<T>): void {
    if (this.nodes.has(IDGenerator.toString(node.id))) return; // 去重
    this.nodes.set(IDGenerator.toString(node.id), node);

    // 1. 寻找左锚点 (优先用 originLeft，找不到退回 originRight 反向查找)
    let leftNode = node.originLeft ? this.nodes.get(IDGenerator.toString(node.originLeft)) : null;
    if (!leftNode) leftNode = this.head; // 兜底插入头部

    // 2. 向右遍历，找到第一个 ID > node.id 的节点，插在其前面
    let curr = leftNode._next;
    while (curr && IDGenerator.compare(curr.id, node.id) < 0) {
      curr = curr._next;
    }
    // 3. 链表拼接
    node._prev = curr?._prev ?? this.tail;
    node._next = curr;
    if (curr) curr._prev = node; else this.tail = node;
    if (node._prev) node._prev._next = node; else this.head = node;
  }

  // 删除：软标记 + 传播
  delete(id: LamportID): void {
    const node = this.nodes.get(IDGenerator.toString(id));
    if (node && !node.deleted) {
      node.deleted = true;
      // 可选：延迟 GC，保留 deleted=true 供撤销/同步
    }
  }

  // 导出可见序列 (渲染层消费)
  toArray(): T[] {
    const res: T[] = [];
    let curr = this.head?._next;
    while (curr) {
      if (!curr.deleted) res.push(curr.value);
      curr = curr._next;
    }
    return res;
  }
}

// packages/crdt-core/src/gc.ts
export class GCController {
  private readonly minRetainSteps = 2000;      // 保留最近 N 步操作
  private readonly maxOfflineDurationMs = 7 * 24 * 3600 * 1000; // 离线容忍 7 天

  // 服务端周期性执行
  prune(docState: DocState, ackVectors: Map<string, StateVector>): number {
    const globalMinClock = Math.min(...ackVectors.values().map(v => v.clock));
    const cutoffClock = globalMinClock - this.minRetainSteps;

    let pruned = 0;
    for (const [idStr, node] of docState.sequence.nodes) {
      if (node.deleted && node.id.clock < cutoffClock) {
        // 二次校验：确认无任何客户端的向量时钟小于该节点 clock
        if (Array.from(ackVectors.values()).every(v => v.clock > node.id.clock)) {
          docState.sequence.nodes.delete(idStr);
          pruned++;
        }
      }
    }
    return pruned;
  }
}

// 连线 CRDT 定义片段
interface EdgeCRDT {
  id: LamportID;
  from: LWWRegister<{ elementId: string; anchor: 'top'|'bottom'|'left'|'right'|'center' }>;
  to:   LWWRegister<{ elementId: string; anchor: 'top'|'bottom'|'left'|'right'|'center' }>;
  style: LWWMap<{ stroke: string; strokeWidth: number; dash?: number[] }>;
  // 语义约束：from.elementId === to.elementId 时自动标记 deleted=true (自环检测)
}

interface UndoManager {
  // 每个客户端维护自己的撤销栈，元素为操作 ID
  localStack: LamportID[];           // 我执行的操作 ID 栈
  redoStack: LamportID[];            // 我撤销的操作 ID 栈
  // 全局视角：每个操作记录其“被谁撤销了”
  undoMap: Map<string, Set<string>>; // opId -> {undoClientIds}
}

function undo(clientId: string, targetOpId?: LamportID): LamportID | null {
  const mgr = getUndoManager(clientId);
  // 1. 确定目标操作：指定 target 或弹出栈顶
  const opId = targetOpId ?? mgr.localStack.pop();
  if (!opId) return null;

  // 2. 生成“反向操作” (Inverse Op)
  const inverseOp = createInverseOperation(opId); // 如：Insert -> Delete, Set(x) -> Set(oldX)
  inverseOp.metadata = { undoOf: opId, undoBy: clientId };

  // 3. 应用反向操作到 CRDT (走正常同步流程)
  crdt.apply(inverseOp);

  // 4. 维护栈状态
  mgr.redoStack.push(opId);
  mgr.undoMap.get(opId.toString())?.add(clientId);

  return inverseOp.id;
}

interface AccessControlEntry {
  subject: string;           // userId / roleId / 'public'
  resource: string;          // docId / 'canvas:elementId'
  actions: ('read'|'write'|'delete'|'comment'|'manage')[];
  conditions?: {             // ABAC 条件
    timeRange?: [start, end];
    ipCidr?: string[];
    deviceTrustLevel?: 'high'|'medium'|'low';
  };
  // CRDT 字段
  grantedBy: LamportID;
  revokedAt?: LamportID;     // 撤销操作 ID
}

┌─────────────────────────────────────┐
│  Application Layer (CRDT Ops)       │ 可靠、有序、持久化 (WebSocket/TCP)
├─────────────────────────────────────┤
│  Awareness Layer (Ephemeral State)  │ 尽力而为、乱序可丢、不持久 (WebRTC DataChannel Unreliable / UDP)
└─────────────────────────────────────┘

// 单用户觉察状态 (约 80-120 bytes 压缩后)
interface AwarenessState {
  clientId: string;
  user: { name: string; color: string; avatar?: string };
  cursor?: { x: number; y: number; timestamp: number }; // 相对画布坐标
  selection?: string[];                                 // 选中元素 ID 列表
  viewport?: { x: number; y: number; zoom: number };    // 视口跟随用
  pointerType?: 'mouse'|'touch'|'pen';
  // 扩展字段：语音音量、视频开关、屏幕共享状态
  media?: { audioLevel: number; videoOn: boolean; sharing: boolean };
}

// plugins/registry.ts
interface ElementSchema {
  type: string;                    // 唯一标识 'chart:bar', 'db:table'
  version: number;                 // Schema 版本
  crdtMapping: {                   // 字段 -> CRDT 类型映射
    props: 'LWWMap';
    data: 'LWWRegister<Json>';     // 图表数据 JSON
    style: 'LWWMap';
  };
  render: (element: ElementCRDT, ctx: CanvasRenderingContext2D) => void;
  hitTest: (element: ElementCRDT, x: number, y: number) => boolean;
  onCreate?: (initialData: any) => Partial<ElementCRDT>; // 工厂函数
  migrate?: (old: any, fromVer: number, toVer: number) => any; // 版本迁移
}

const registry = new Map<string, ElementSchema>();

export function registerElement(schema: ElementSchema) {
  if (registry.has(schema.type)) throw new Error(`Duplicate type: ${schema.type}`);
  registry.set(schema.type, schema);
}

// plugins/live-data-binding.ts
class LiveDataBindingPlugin {
  private subscriptions = new Map<string, AbortController>();

  // 元素属性中声明绑定: { bind: { source: 'clickhouse', queryId: 'sales_daily', interval: 10000 } }
  onElementMount(element: ElementCRDT) {
    const bind = element.props.bind;
    if (!bind) return;

    const controller = new AbortController();
    this.poll(bind, element, controller.signal);
    this.subscriptions.set(element.id, controller);
  }

  private async poll(bind: BindConfig, element: ElementCRDT, signal: AbortSignal) {
    while (!signal.aborted) {
      const data = await fetchDataSource(bind.source, bind.queryId);
      // 关键：通过 CRDT 更新数据字段，自动同步到所有协作者
      element.props.data.set(data); // LWWRegister.set()
      await sleep(bind.interval);
    }
  }

  onElementUnmount(elementId: string) {
    this.subscriptions.get(elementId)?.abort();
  }
}

// 审计日志条目 (仅追加，不可变)
interface AuditLogEntry {
  logId: string;              // UUIDv7
  timestamp: number;          // 服务器可信时间戳
  actor: { userId: string; ip: string; deviceFingerprint: string };
  action: 'create'|'update'|'delete'|'permission_change'|'export'|'share';
  resource: { docId: string; elementIds?: string[] };
  beforeHash: string;         // 操作前文档状态 Merkle Root
  afterHash: string;          // 操作后文档状态 Merkle Root
  signature: string;          // 服务端私钥签名 (防篡改)
}

// 在 RGASequence 内部维护跳表，仅索引未删除节点
private skipList: SkipList<LamportID, SeqNode<T>>; // 基于 ID 全序

integrate(node: SeqNode<T>) {
  // ... 原有链表逻辑 ...
  this.skipList.insert(node.id, node); // O(log N)
}

// 查找插入位置：跳表定位前驱，再链表微调
findInsertPosition(id: LamportID): SeqNode<T> | null {
  return this.skipList.findLessThan(id) ?? this.head;
}

whiteboard-collab/
├── packages/
│   ├── crdt-core/          # 纯算法库 (零依赖, 发布 npm)
│   ├── crdt-yjs-adapter/   # Yjs 兼容层 (可选)
│   ├── sync-engine/        # 网络/存储/离线 (Node + Browser)
│   ├── render-engine/      # Canvas/OffscreenCanvas 渲染核心
│   ├── awareness/          # 觉察通道实现
│   ├── plugins/            # 官方插件集 (图表、思维导图、数据绑定)
│   ├── ui-components/      # React/Vue/Svelte 无关 UI 原语
│   └── demo-app/           # 集成演示应用
├── tools/
│   ├── perf-benchmark/     # k6 脚本 + 自动化火焰图分析
│   ├── chaos-test/         # 网络分区/时钟漂移/乱序注入器
│   └── schema-validator/   # CRDT 文档结构合法性校验
└── docker/                 # 同步服务/信令服务/网关 镜像定义

# .github/workflows/ci.yml
jobs:
  crdt-correctness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Property-based Testing (fast-check)
        run: pnpm -F crdt-core test:prop   # 10k 随机操作序列验证收敛性
      - name: Concurrent Simulation (10 clients x 1000 ops)
        run: pnpm -F crdt-core test:concurrent

  performance-regression:
    runs-on: [self-hosted, gpu, high-perf] # 固定硬件基准机
    steps:
      - name: Run Render Benchmark (5000 elements)
        run: pnpm -F render-engine bench:render
      - name: Compare with Baseline (threshold: +5%)
        uses: benchmark-action/github-action-benchmark@v1

  e2e-collab:
    runs-on: ubuntu-latest
    services:
      sync-server: { image: whiteboard/sync:latest }
    steps:
      - name: Playwright Multi-tab Test (5 tabs)
        run: pnpm -F demo-app test:e2e:collab