mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md

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

> 更新时间：2026-04-29
>
> 关联文档：
> - `/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

用于：

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

建议形状：

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

### 5.2 Subtree stream

用于：

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

建议形状：

```json
{
  "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`

参考形状：

```json
{
  "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` 或文档页
- 实时链路失败时，首屏仍要有稳定 snapshot fallback

也就是说：

- 首屏可用性优先于实时增强
- 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-04-29）

这份方案继续留在 `process/`，因为 Rust Web transport 已落地，但当前 `3000` 的 Rust SSR tree/sidebar 消费侧还没有完整闭环到 live stream。

### 9.1 已完成

- [x] Rust Web 已暴露正式 `/api/tree/events`，并返回 `x-mnote-web-owner: mnote-web` 与 `x-mnote-tree-stream-owner: rust-web`。
- [x] `/api/tree/events` 已能输出 workspace / subtree snapshot。
- [x] `stream_support.rs` 已有 cursor、delta、resync 的基础判定逻辑。
- [x] `/api/stream/events` 与 WebSocket snapshot / resync 骨架已存在。
- [x] legacy React 侧已有 `useSidebarTreeStream` 与 `EventSource` consumer，并有协议 / delta 单测。
- [x] `task112` / `task120` 已覆盖 `/api/tree/events` snapshot 可用性。

### 9.2 仍未完成

- [ ] 当前 Rust Web 3000 SSR workspace/sidebar shell 还没有直接挂载 live `EventSource` consumer；它主要依赖 SSR snapshot 与交互后重读。
- [ ] delta / resync 尚缺面向当前 3000 Rust shell 的浏览器级 smoke。
- [ ] Sidebar、page subtree、filetree 还没有全部统一到同一条 live stream cache。
- [ ] WS 目前只证明 snapshot/resync 骨架，尚未成为主实时链路。
- [ ] 不能把本稿移动到 `done/`，直到 `3000` 当前主界面的树消费侧也完成 snapshot + delta + resync 验收。