企业级云端协同笔记系统架构设计：从状态同步机、目录树到版本快照回滚

┌────────────────────────────────────────────────────────┐
│ 前端展现层 (Vue 3 / React + TailwindCSS + Pinia/Zustand)│
│  ├── 知识库无限虚拟目录树 (Virtual Tree)                │
│  ├── Tiptap 富文本 / Block 块级编辑器容器               │
│  └── 协同光标与在线感知头像条 (Awareness Avatars)        │
├────────────────────────────────────────────────────────┤
│ 协同与通信层 (Yjs + WebSocket + Hocuspocus Client)     │
│  ├── 协同同步状态机 (Sync State Machine)                │
│  ├── 离线持久化适配器 (IndexedDB Provider)              │
│  └── 冲突自动合并引擎 (CRDT YATA Engine)                │
├────────────────────────────────────────────────────────┤
│ 服务端核心中台 (Hocuspocus Server + Node.js / Hono)     │
│  ├── 房间会话管理与 WebSocket 广播 (Pub/Sub)            │
│  ├── JWT 多租户权限与文档读写隔离                      │
│  └── 自动去抖与增量快照引擎 (Snapshot Worker)           │
├────────────────────────────────────────────────────────┤
│ 持久化存储层 (PostgreSQL + S3 对象存储 + Redis)         │
│  ├── PostgreSQL: 文档元数据、目录关系、用户权限 RBAC    │
│  ├── S3 存储桶: 历史版本全量快照、图片与附件            │
│  └── Redis: 分布式在线状态与心跳缓存                   │
└────────────────────────────────────────────────────────┘

[未连接 DISCONNECTED]
  │
  ▼ 发起 WebSocket 连接
[连接中 CONNECTING]
  │
  ▼ 握手与鉴权成功
[同步中 SYNCING] ──► 从服务端拉取初始缺失的 Yjs Updates
  │
  ▼ 同步完成
[已同步 SYNCED] ◄───► [有本地未保存更改 SAVING]
  │
  ▼ 遭遇弱网/断网
[离线编辑 OFFLINE] ──► 自动存入本地 IndexedDB，重连后自动合并

export type SyncStatus = 'disconnected' | 'connecting' | 'syncing' | 'synced' | 'saving' | 'offline';
 
export interface DocumentState {
  id: string;
  title: string;
  syncStatus: SyncStatus;
  onlineUsers: Array<{
    id: string;
    name: string;
    avatar: string;
    color: string;
  }>;
  isReadOnly: boolean;
}

import * as Y from 'yjs';
import { IndexeddbPersistence } from 'y-indexeddb';
import { HocuspocusProvider } from '@hocuspocus/provider';
 
export function createCollaborativeDoc(docId: string, token: string) {
  const ydoc = new Y.Doc();
 
  // 1. 本地秒开：优先从浏览器的 IndexedDB 秒级加载文档内容
  const idbProvider = new IndexeddbPersistence(`note-doc-${docId}`, ydoc);
 
  idbProvider.on('synced', () => {
    console.log('本地 IndexedDB 已完成加载，页面可立即交互');
  });
 
  // 2. 云端连接：在后台并发建立 WebSocket 长连接
  const wsProvider = new HocuspocusProvider({
    url: 'wss://collab.example.com',
    name: docId,
    document: ydoc,
    token,
  });
 
  return { ydoc, idbProvider, wsProvider };
}