mnote/design/old/04-tree-domain/process/4-9-tree-rust-family-cutover-remaining-architecture-and-capability-preservation-v1.md

# 4-9 [recycle] 树域 Rust 家族化剩余架构事项与能力保留方案 v1

> 更新时间：2026-04-23
>
> 回收说明（2026-04-28）：本文是 Rust 家族化下一阶段的早期架构拆解稿，后续已由 `4-10` 执行清单、`4-11` final renderer / host thinning、`4-16` remaining final runtime、`4-18` final DOM shell hard gate 继续拆分和覆盖。本文保留为历史能力保留口径，不再作为当前活跃 `process` 入口。
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-2-sidebar-pagetree-filetree-product-interaction-contract-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-4-tree-projection-protocol-contract-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-7-tree-shell-ui-state-boundary-v1.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`

## 1. 文档目的

这份文档只回答两个问题：

1. 在当前长期方向已经固定为 `Rust kernel + Rust web + Leptos island + Convex substrate` 的前提下，树域继续朝 Rust 家族化推进，还剩哪些真正的架构事项。
2. 在 `page tree / file tree` 从当前 `TypeScript + Next + React` 主壳向 Rust 家族执行面迁移时，哪些现有能力必须被完整保留，不能为了“换语言”而退化。

这份文档不是为了重复证明：

- `Convex` 是否还保留
- 树域是否已经具备 projection contract
- `Page Aggregate` 是否应该存在

这些上位结论已经在关联文档中固定。

本文只做当前阶段最需要的补充收口：

> **树域已经完成 truth / projection / command 边界的第一轮收口，但主渲染壳仍主要停留在 `TypeScript + Next + React`。下一阶段要解决的，不再是“树是不是 kernel projection”，而是“树域主执行面怎样继续向 Rust 家族迁移，同时不丢掉现有交互能力”。**

---

## 2. 当前判断

## 2.1 已经成立的部分

当前已经成立且不应回退的事实：

- `tree-first graph kernel` 继续是树域真相层。
- `Convex` 继续承担存储、实时同步、内容与协作底座。
- `mnote-web` 已经具备树域 projection / command / transport 的正式入口能力。
- `sidebar_tree / page_tree / file_tree` 已经形成同一 projection family。
- 树域主路径不应再回到“前端自己定义第二套树真相”。

也就是说，当前真正成立的结构是：

- `Rust kernel` 持有树语义。
- `Convex` 提供 substrate。
- `Rust web` 已开始承接 route / projection / command / stream。
- 当前主站中的树 consumer 已经开始消费 projection family。

## 2.2 仍未完成的部分

当前仍未完成、且正是下一阶段主任务的部分是：

- `page tree / file tree / picker` 的主渲染壳仍主要是 `TypeScript + Next + React`。
- `file_tree` 的一部分 row 语义仍由前端 adapter 继续补齐，而不是完全由 Rust 直接输出。
- `tree.*` 的长期命令面虽已冻结，但主调用路径仍未完全退出 `documents.*` 兼容入口。
- 树域 realtime 仍未完全收口为 Rust Web 正式 `snapshot + delta + resync` 主链。
- Sidebar 整体仍是超大客户端壳，树域虽然已收 truth，但执行面与宿主边界还不够薄。

因此当前正确判断不是：

- “树域 Rust 家族化已经完成”

而是：

> **树域已经完成“语义与协议收口”，但还没有完成“主执行面 Rust 家族化”。**

---

## 3. 为什么继续 Rust 家族化有真实意义

## 3.1 不是语言洁癖，而是减少第二套运行时语义

如果长期保持下面这种结构：

- Rust 负责 kernel / query / command / projection
- Next/React 继续负责主树 UI、主交互壳、主状态骨架

那么树域会长期同时维护两套复杂度：

1. Rust 侧的 projection / command / stream 语义
2. 前端壳里的 row model / selection / focus / keyboard / DnD / fallback / adapter 语义

这会带来：

- 协议在两侧重复解释
- 调试时要同时跨 TS / Rust 两套执行面
- tree shell 的边界始终无法真正稳定
- 后续一切性能优化都要先穿过旧前端壳

因此这里的“继续 Rust 家族化”真正要减少的，不是文件后缀的种类，而是：

> **树域存在两套长期执行语义的状态。**

## 3.2 对加载速度与运行成本有真实潜力

树域是高频常驻 UI，不是偶尔打开一次的边缘面板。

如果它继续作为大型 `use client` 组件族存在，就会长期保留这些成本：

- 客户端组件挂载
- 虚拟列表初始化
- DnD 状态机初始化
- 菜单与选择状态初始化
- 浏览器侧 row model 构建
- 兼容 fallback 与 stream 选择逻辑

这些成本不会因为“数据真相已经交给 Rust”而自动消失。

把树域主壳继续迁向 Rust 家族，真实收益主要来自：

- 进一步压低浏览器端常驻 JS
- 让 projection -> renderer 的路径更短
- 减少 hydration 与挂载层数
- 降低 Sidebar 切页与刷新时的重渲染放大
- 为后续更彻底的 server-first 壳收口创造条件

这里必须强调：

- Rust 化 **不自动等于** 更快
- 但在当前项目的长期方向里，Rust 家族化是“继续减轻旧前端壳”的必要手段

## 3.3 对协作冲突与长期维护也有真实意义

这里的“冲突”不只指 git merge 冲突，更主要是：

- projection contract 与 renderer 行为漂移
- TS adapter 与 Rust route 的边界反复变化
- 同一个交互在两侧同时维护 legality / normalization / fallback

当树域主执行面仍留在 React 壳里时：

- Rust 改协议
- 前端就要继续补 adapter
- 测试也要跨两族运行时拼接验证

继续 Rust 家族化的意义，是让下面这条链尽量收敛为一条语言家族更统一的主链：

- kernel truth
- projection
- tree command
- tree shell
- renderer

---

## 4. 下一阶段剩余架构事项

下面这些事项，才是树域继续 Rust 家族化时真正还没完成的主任务。

## 4.1 正式定义“树域主执行面”的完成标准

首先必须明确：

- “树域已经吃 projection” 不等于 “树域已经 Rust 家族化完成”
- “存在 Leptos scaffold / Rust tree_shell 模块” 不等于 “主路径 renderer 已迁完”

下一阶段完成标准应固定为：

- 至少一条真实默认用户流量，主树 renderer 不再依赖当前 React `PrivateTree` / `FileTree`
- `page tree / file tree / picker` 的核心交互骨架不再由 Next/React 主壳承担
- TS 宿主只保留挂载、局部桥接、页面路由与极薄 compat

如果这一标准不先冻结，后续很容易再次把“有 Rust route”误当成“已经 Rust 化完成”。

## 4.2 把 page tree renderer 真正迁入 Rust 家族

`page tree` 下一阶段不是继续补前端 helper，而是把以下能力迁成 Rust 家族正式 renderer 能力：

- 行渲染
- 展开/折叠
- 当前页高亮
- hover 动作区
- 键盘导航
- 拖拽反馈
- 上下文菜单入口

这里的重点不是“把视觉样式翻译一遍”，而是：

- 把行级行为骨架从 React 组件迁走
- 让 page tree 只围绕正式 projection item 工作
- 不再由现有 TS 组件长期持有主路径交互状态机

## 4.3 把 file tree 从“前端 adapter 文件树”收口为“Rust 直接输出 + Rust 家族 renderer”

`file_tree` 是当前最关键也最容易退化的一段。

下一阶段必须同时做两件事：

1. Rust 侧继续把 `file_tree` 输出补完整。
2. renderer 不再依赖当前前端在 `pageRows + assets` 上继续拼 visible rows。

必须继续向 Rust 收口的内容包括：

- `index.md`
- 附件
- `mindmap` 文件夹
- 导图子附件
- 表格、书籍、PDF 等对象提示
- `resource_kind / asset_kind / icon_hint`

否则文件树即使换了新壳，也仍然只是：

- “页面树 + 前端附件补丁”

这不符合长期目标。

## 4.4 把树域交互骨架拆成可替换的正式模块

下一阶段不应继续把交互都堆在单一大组件里，而应显式收口为几类正式模块：

- row model
- selection model
- focus model
- keyboard model
- DnD state machine
- context action registry

无论这些模块最终落在：

- `Leptos`
- 或极薄 Rust/TS bridge

都必须满足两条：

- 它们不再定义结构真相
- 它们可以独立测试与演进

## 4.5 完成 tree command cutover Stage 2

树域继续 Rust 家族化时，命令面不能长期继续停在双轨。

下一阶段必须完成：

- 主路径默认发 `tree.*`
- `documents.*` 退到 compat
- legality / normalize / move target 等树策略继续回收给 Rust

否则会出现一个长期问题：

- UI 壳换成 Rust 家族了
- 但命令面仍主要经由旧 `documents.*` 兼容语义运行

这样并没有完成真正的主执行面收口。

## 4.6 完成 Rust Web realtime contract

树域如果要继续往正式主链推进，realtime 必须从“可用”进入“单一正式合同”。

下一阶段需要补齐：

- `snapshot`
- `delta`
- `resync`
- cursor 漂移处理
- 局部 subtree 与 workspace scope 的统一

目标不是简单保住 fallback，而是让树域主路径不再依赖：

- 查询快照
- 本地 freshness 选择
- React 侧补偿式同步

## 4.7 收薄宿主边界

长期目标不是让主站彻底消失，而是让主站对树域只保留最小宿主职责：

- 页面布局挂载位
- 路由跳转
- 样式容器
- 极薄 feature flag / compat
- 与其他页面面板的最小桥接

不应继续保留在宿主中的内容：

- 树结构重建
- 主交互状态骨架
- 文件树资源行语义补丁
- 主要 keyboard / DnD / selection 逻辑

---

## 5. page tree 迁移时必须保留的能力

`page tree` 在迁移到 Rust 家族主执行面时，必须显式保证下面这些能力不退化。

## 5.1 结构与导航

必须保留：

- 稳定的层级展开/折叠
- 当前页高亮
- 祖先自动展开
- 搜索/过滤后层级仍可理解

禁止退化为：

- 纯扁平列表
- 只有打开功能、没有层级语义的按钮组

## 5.2 行级动作

必须保留：

- 新建子页面
- 重命名
- 移动
- 归档/恢复类上下文操作入口
- 行级 hover 动作区

要求：

- 不能为了换 renderer 把动作缩减到“点开页面 + 更多菜单”
- 不能丢失当前工作区级高频动作入口

## 5.3 键盘与焦点

必须保留：

- 上下移动
- 左右展开/折叠
- Enter 打开
- 稳定的 focus 行

要求：

- `focus` 不能重新混成 `selected`
- 展开与选择变化后焦点归一化必须稳定

## 5.4 拖拽与移动

必须保留：

- 基础拖拽排序
- 父节点切换
- 非法拖拽校验

要求：

- drop feedback 不能退化成不可预测的闪烁
- 目标父节点与位置推导必须有稳定、可测试的协议

## 5.5 大树体验

必须保留：

- 稳定滚动
- 大树下的可见区域性能
- 展开/折叠与切页不会出现明显回闪

这部分是迁移时的硬验收项，不是可选优化项。

---

## 6. file tree 迁移时必须保留的能力

`file_tree` 比 `page tree` 更容易因迁移而退化。

下一阶段必须把“功能保留”明确写成硬门槛。

## 6.1 资源层级

必须保留：

- 页面
- `index.md`
- 附件
- `mindmap` 文件夹
- 导图子附件
- 表格、书籍、PDF 等资源对象语义

禁止退化为：

- 页面树下挂一个普通附件列表
- mindmap 资源被拍平成普通文件

## 6.2 选择能力

必须保留：

- 单选
- 多选
- Shift 范围选
- 右键选中
- 可见行变化后的选择归一化

这部分如果退化，文件树就不再是资源管理器语义，而会退回文档树换皮。

## 6.3 打开与操作

必须保留：

- 单击选择
- 双击打开资源
- 资源级右键菜单
- 按资源类型分支的动作入口

要求：

- 资源图标语义必须稳定
- `asset_kind / icon_hint` 不允许再次回到壳内临时猜测

## 6.4 拖放

必须保留：

- 内部拖放
- 外部文件拖入上传
- copy / move 区分
- 非法投放校验

要求：

- 文件树不能只保留视觉拖拽，没有正式动作协议
- 外部文件拖入必须继续是正式主路径能力

## 6.5 文件树特有的可见行模型

必须保留：

- `doc -> index -> asset-folder -> asset` 的可见行语义
- 扁平化 rows 与深度的稳定映射
- 可见行变化后的选择、焦点、拖放范围归一化

这里允许实现换掉，但不允许语义丢掉。

---

## 7. 推荐迁移顺序

为了尽量保持体验不退化，推荐顺序如下：

1. 先补齐 `file_tree` 的 Rust 直接输出，避免迁 renderer 时还要继续背前端 adapter。
2. 再把 `page tree` renderer 迁入 Rust 家族，因为它对象更单纯、验收面更小。
3. 然后迁 `file tree` renderer，因为它依赖更多资源与交互语义。
4. 再迁 `picker` 轻量模式，让它复用同一套 renderer / state family。
5. 最后继续削薄宿主，收掉剩余主路径 React 树壳。

原因：

- `page tree` 先迁可以先验证主行 renderer 与状态骨架。
- `file_tree` 后迁可以避免一开始就在最复杂对象面上同时处理 renderer 与 contract 漂移。
- `picker` 最适合作为共用 renderer 的轻量消费场景，而不是主线路的先导。

---

## 8. 迁移阶段的验收门槛

只有同时满足下面几条，才可以把树域继续 Rust 家族化的某一阶段视为成立：

- 页面树与文件树都没有因切流而减少已有能力。
- `page tree / file tree` 的关键能力有 smoke 覆盖：
  - 切页
  - 展开/折叠
  - 拖拽
  - 右键菜单
  - 多选与范围选
  - 外部文件拖入
- `file_tree` 的对象投影不再依赖前端临时补丁维持主路径。
- 主调用路径默认走正式 `tree.*` 命令面。
- 正式 realtime 至少已经进入统一 `snapshot + delta + resync` 合同，而不是继续主要靠补偿式 freshness 选择。
- 主站宿主不再持有树结构真相，也不再承担主要树域交互状态机。

---

## 9. 当前优先级建议

在当前总优先级下，树域继续 Rust 家族化的最近顺序建议固定为：

1. 继续推进 `4-6 tree command protocol cutover stage2`
2. 明确 `file_tree` 直接输出的剩余缺口，并以 Rust 侧补齐
3. 为 `page tree / file tree` 迁移补正式功能保留回归矩阵
4. 选择并落一条真实默认流量进入 Rust 家族 renderer
5. 再逐步收掉当前主路径 React 树壳

也就是说，当前下一步不是：

- 继续在现有 React 树壳里堆更多交互补丁

而是：

> **在功能不退化的前提下，把树域从“Rust 持有语义、React 持有主执行面”的过渡态，推进到“Rust 家族同时持有语义与主执行面”的下一阶段。**

---

## 10. 最终结论

当前树域继续往全 Rust 方向发展，是有真实意义的。

意义不在于：

- 代码库里减少一种语言

而在于：

- 收掉旧前端壳的长期主执行职责
- 减少第二套复杂运行时语义
- 为首屏与常驻交互链路继续减重
- 让 `tree-first graph kernel -> Rust Web -> Rust family shell` 形成更一致的长期主链

但这个推进必须满足一个前提：

> **page tree / file tree 的功能能力不能因为迁移而退化。**

因此，下一阶段的正确目标不是“尽快把组件翻译成 Rust”，而是：

> **先把剩余 projection / command / realtime / host 边界补齐，再以 page tree 与 file tree 的能力保留为硬约束，把树域主执行面稳步迁入 Rust 家族。**