lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2f9ef85350055aed856b7a121bec3f396b56964b
mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md
T

7.2 KiB
Raw Blame History

3-3 [process] Rust Web Tree Realtime Event Stream 方案 v1

更新时间：2026-05-09

关联文档：

  • /mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/process/2-tree-first-graph-convex-rust-long-term-architecture-v1.md
  • /mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md
  • /mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md

1. 目标

这份文档用于固定 Stage C-1 的正式实时链路口径：

  • 保留 Convex 作为 realtime substrate
  • Rust 成为 tree-first graph 的 semantic owner
  • Rust Web 负责正式页面 transport 与实时事件流
  • 前端只消费 projection 与 delta，不再消费实验壳真相

目标效果是接近网页版 wolai / notion 的体验：

  • 快速进入页面
  • 树结构实时同步
  • 局部变化快速响应
  • 浏览器端不持有第二套树真相

2. 职责划分

2.1 Convex substrate

Convex 继续承担：

  • 持久化
  • mutation / query 底座
  • 实时订阅底座
  • 文件 / 对象存储协作

Convex 在这里是：

storage / realtime substrate

而不是页面树语义 owner。

2.2 Rust semantic owner

Rust kernel 负责：

  • page_tree / sidebar_tree / file_tree / subtree 语义
  • node / edge / projection 规则
  • command / query 的语义收口
  • domain event 的统一格式
  • trace / audit / version 口径

Rust 在这里是：

Rust semantic owner

2.3 Rust Web transport

Rust Web 负责：

  • SSR 页面壳
  • SSE / WS 主链
  • workspace / subtree 订阅入口
  • 把 Convex 订阅与 Rust domain event 连接起来
  • 向前端输出稳定的 projection snapshot + delta stream

2.4 前端 projection consumer

前端只负责：

  • 首屏渲染
  • islands 交互
  • optimistic UI
  • 应用 delta 到本地 projection cache

前端不再负责：

  • 重新定义树结构
  • 重新计算页面树语义
  • 维护实验壳 iframe 作为正式实时主链

3. 为什么当前 tree shell 不是正式实时链路

当前 mnote-web tree shell 仍然只是实验壳，原因有三点：

  1. 它依赖 iframe / HTML shell / postMessage 交互。
  2. 它的 command path 和状态边界更接近实验 viewer，而不是正式页面 transport。
  3. 它没有成为首页、sidebar、文档页共享的正式实时订阅主链。

因此当前 tree shell 可以继续保留为：

  • 实验验证壳
  • 独立 tree viewer
  • picker / filetree 的可选增强壳

但不能继续当成正式 realtime 主链。

4. 正式 realtime tree event stream 分层

正式链路建议固定为四层：

4.1 Convex 持久化/订阅底座

这里负责：

  • 命令落账
  • 持久化页面树状态
  • 输出 mutation 后可订阅的数据变化

4.2 Rust kernel 语义 owner

这里负责：

  • 把命令结果解释为 domain event
  • 把底层 mutation 变化转成树域可消费的语义事件
  • 维护 projection rebuild 与 delta 生成规则

4.3 Rust Web SSE/WS transport

这里负责：

  • 暴露正式 /api/tree/events 或等价 stream 入口
  • 管理 workspace / subtree 订阅
  • 发送 snapshot、delta、cursor、ack、resync 信号

推荐策略：

  • 首屏与重连优先使用 snapshot
  • 连续变化优先推送 delta
  • 大规模漂移或 cursor 失配时回退到 resync snapshot

4.4 前端 projection consumer

这里负责：

  • 接收初始 projection snapshot
  • 接收增量事件
  • 合并到 sidebar / filetree / page subtree cache
  • 必要时触发局部重渲染

5. 建议事件形状

正式事件建议至少覆盖三类 scope：

  • workspace
  • subtree
  • tree delta

5.1 Workspace stream

用于：

  • 当前工作区根树更新
  • 垃圾桶、模板、共享页等全局区域变化

建议形状：

{
  "stream": "workspace",
  "workspaceId": "ws_123",
  "cursor": "evt_1001",
  "kind": "snapshot|delta|resync",
  "projection": "sidebar_tree",
  "data": {}
}

5.2 Subtree stream

用于：

  • 当前文档子树
  • file tree 局部展开区域
  • picker 只关注的局部节点集合

建议形状：

{
  "stream": "subtree",
  "workspaceId": "ws_123",
  "rootNodeId": "page_1",
  "cursor": "evt_1002",
  "kind": "snapshot|delta|resync",
  "projection": "page_tree",
  "data": {}
}

5.3 Tree delta payload

建议包含：

  • eventId
  • commandId
  • traceId
  • aggregateType
  • aggregateId
  • op
  • node
  • parentNodeId
  • position
  • removedNodeIds
  • changedProjectionKeys

参考形状：

{
  "eventId": "evt_1003",
  "commandId": "cmd_2001",
  "traceId": "trace_3001",
  "aggregateType": "page",
  "aggregateId": "page_9",
  "op": "create|rename|move|delete|restore|purge|embed",
  "node": {
    "id": "page_9",
    "title": "新页面"
  },
  "parentNodeId": "page_root",
  "position": 3,
  "removedNodeIds": [],
  "changedProjectionKeys": ["sidebar_tree", "file_tree"]
}

6. 与首页和首屏的关系

首页与 /api/sidebar 的 P0 原则必须保持不变：

  • 首页不能再依赖 3104 实验壳
  • 3000 主入口必须可稳定进入 /auth 或文档页
  • 首屏仍要有稳定 SSR snapshot，但不再通过第二条 runtime projection fallback 偷偷补拉 live 语义

也就是说：

  • 首屏可用性优先于实时增强
  • realtime stream 是正式增强层，不是新的首屏阻塞点

7. 实施顺序

推荐顺序如下：

  1. 先固定首页、sidebar、picker 不再依赖 tree shell 实验壳。
  2. 再固定 Rust kernel 的 tree command / projection owner 身份。
  3. 然后补正式 Rust Web SSE/WS tree stream。
  4. 最后把 sidebar、page subtree、filetree 逐步切到统一 stream。

8. 最终固定口径

长期口径固定为：

  • Convex substrate 不拆
  • Rust semantic owner 收口语义
  • Rust Web 提供正式实时 transport
  • 前端只消费 projection snapshot 与 tree delta
  • iframe/postMessage tree shell 不是正式 realtime 主链

9. 当前实现复核（2026-05-09）

这份方案继续留在 process/，因为 Rust Web transport 与当前 3000 主壳 live consumer 已落地，但 page subtree / filetree / preferred snapshot 仍未完全统一到同一条正式 live cache。

9.1 已完成

  • Rust Web 已暴露正式 /api/tree/events，并返回 x-mnote-web-owner: mnote-web 与 x-mnote-tree-stream-owner: rust-web。
  • /api/tree/events 已能输出 workspace / subtree snapshot。
  • stream_support.rs 已有 cursor、delta、resync 的基础判定逻辑。
  • /api/stream/events 与 WebSocket snapshot / resync 骨架已存在。
  • legacy React 侧已有 useSidebarTreeStream 与 EventSource consumer，并有协议 / delta 单测。
  • 当前 3000 Rust shell 已直接挂载 tree live EventSource consumer，并通过 data-mnote-tree-live-applied 应用 delta / resync。
  • task112 / task120 / task123 已覆盖 /api/tree/events snapshot、delta / resync 与 stream owner 可用性。
  • task165 已验证双 pane 不重复建立第二条 tree live stream。

9.2 仍未完成

  • Sidebar、page subtree、filetree 还没有全部统一到同一条 live stream cache。
  • WS 目前只证明 snapshot/resync 骨架，尚未成为主实时链路。
  • 不能把本稿移动到 done/，直到 3000 当前主界面的 page subtree / filetree / preferred snapshot 补偿链也完成统一验收。
Reference in New Issue View Git Blame Copy Permalink