527 lines
13 KiB
Markdown
527 lines
13 KiB
Markdown
# 4-1 [recycle] Sidebar / 页面树 / 文件树 产品级差距分析 v1
|
||
|
||
> 更新时间：2026-04-17
|
||
>
|
||
> 关联文档：
|
||
> - `/mnt/Data1T/mnote/design/04-tree-domain/process/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md`
|
||
> - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`
|
||
> - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-1-tree-first-graph-kernel-checklist-v2.md`
|
||
|
||
## 1. 文档目的
|
||
|
||
这份文档不回答：
|
||
|
||
- “当前新树能不能先凑合继续用”
|
||
- “再补一点样式是不是就够了”
|
||
|
||
这份文档回答的是：
|
||
|
||
> **当前 git 中已经接入的 Rust Web tree shell，距离“文件树对标 VS Code、页面树对标 Wolai / Notion”的产品目标还差什么，以及下一步应该如何推进。**
|
||
|
||
结论先固定：
|
||
|
||
- 当前方向没有跑偏
|
||
- 当前实现仍然只是过渡 shell，不是产品级树控件
|
||
- 下一步重点不是继续修饰过渡 shell，而是进入“产品级树域控件重建”
|
||
|
||
---
|
||
|
||
## 2. 当前实现所处阶段
|
||
|
||
根据当前 git 中未提交改动，现状应被定义为：
|
||
|
||
- 已完成 tree shell 挂载位
|
||
- 已完成 `mnote-web /tree` 路由与基本 command 回写
|
||
- 已完成 Sidebar / 文件树 / picker 的渐进切流入口
|
||
- 尚未完成产品级树交互能力重建
|
||
|
||
也就是说，当前完成的是：
|
||
|
||
- **协议验证**
|
||
- **切流验证**
|
||
- **最小可运行壳验证**
|
||
|
||
而不是：
|
||
|
||
- **VS Code 级文件树**
|
||
- **Wolai / Notion 级页面树**
|
||
|
||
### 2.1 当前代码中已经成立的部分
|
||
|
||
- `wolai-frontend` 已经可以把树域挂到 `mnote-web tree shell`
|
||
- `mnote-web` 已经可以输出基础 tree projection 并承接 create / rename / move
|
||
- 新旧树之间已经有 feature flag 与 fallback
|
||
|
||
对应实现可参考：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/sidebar.tsx`
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/MnoteWebTreeShell.tsx`
|
||
- `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/tree.rs`
|
||
|
||
### 2.2 当前实现不能被误判为“已完成重构”的原因
|
||
|
||
当前 `mnote-web tree shell` 仍然具有明显过渡壳特征：
|
||
|
||
- 通过 `iframe + postMessage + fallback` 接入主站
|
||
- 壳内 UI 仍是手写 HTML / CSS / DOM 逻辑
|
||
- 交互动作仍大量依赖 `prompt` / `alert`
|
||
- 没有完成稳定的 row model / focus model / selection model / keyboard model / DnD state machine
|
||
|
||
这类实现适合做：
|
||
|
||
- 协议对齐
|
||
- route 验证
|
||
- 真机切流
|
||
|
||
不适合直接作为：
|
||
|
||
- 最终产品树控件
|
||
|
||
---
|
||
|
||
## 3. 现阶段的关键判断
|
||
|
||
### 3.1 方向没有错
|
||
|
||
当前路线与长期架构是一致的：
|
||
|
||
- 树真相继续下沉到 kernel / projection
|
||
- 页面树与文件树继续作为 projection family
|
||
- Sidebar 继续降级为树域承载壳
|
||
|
||
所以，“把树域逐步从旧 React 组件中剥离出来”这个方向是对的。
|
||
|
||
### 3.2 体验回退是阶段性真实现象
|
||
|
||
用户现在觉得新树在操作和界面上与目标产品差距很大，这个判断是正确的。
|
||
|
||
原因不是：
|
||
|
||
- 目标错了
|
||
|
||
而是：
|
||
|
||
- 当前切进去的是过渡 shell
|
||
- 旧 React 树实际上已经沉淀了一部分成熟交互
|
||
- 新 Rust Web 壳还没有把这些产品交互能力重新建起来
|
||
|
||
### 3.3 当前最危险的误区
|
||
|
||
当前最应该避免的，不是“改慢一点”，而是下面两个误区：
|
||
|
||
- 误区 A：把过渡 shell 继续当最终产品打磨
|
||
- 误区 B：看到效果差，就退回“继续长期维持旧树 + 新协议双轨”
|
||
|
||
正确做法是：
|
||
|
||
- 承认当前只是过渡壳
|
||
- 用它验证协议与切流
|
||
- 然后进入产品级树控件重建
|
||
|
||
---
|
||
|
||
## 4. 当前实现与目标产品的差距矩阵
|
||
|
||
## 4.1 文件树：目标应对标 VS Code Explorer
|
||
|
||
这里的“对标”不是抄界面，而是对标：
|
||
|
||
- 行为模型
|
||
- 信息密度
|
||
- 交互反馈
|
||
- 结构表达
|
||
|
||
### 当前已经具备的部分
|
||
|
||
- 已有文件树入口
|
||
- 已有页面与附件的基础层级表达
|
||
- 已有打开页面 / 打开附件的最小动作链路
|
||
- 主站旧文件树中已沉淀部分 VS Code 风格拖放语义
|
||
|
||
### 当前缺失的关键能力
|
||
|
||
- 缺少稳定的文件树专用 row model
|
||
- 缺少真实的 `filetree` 模式闭环
|
||
- 缺少多选与连续选择
|
||
- 缺少键盘导航
|
||
- 缺少目录型拖放状态机
|
||
- 缺少重命名内联编辑
|
||
- 缺少右键菜单体系
|
||
- 缺少 hover 工具动作
|
||
- 缺少大树虚拟化与增量展开策略
|
||
- 缺少图标语义与资源类型区分
|
||
|
||
### 当前与 VS Code 的本质差距
|
||
|
||
当前新壳更像：
|
||
|
||
- “能渲染树结构的调试页”
|
||
|
||
而 VS Code Explorer 是：
|
||
|
||
- “高密度、可键盘驱动、可多选、可拖放、可重命名、可上下文操作的文件资源管理器”
|
||
|
||
所以文件树下一阶段不应再以“补几个按钮”为目标，而应以“重建 Explorer 行为模型”为目标。
|
||
|
||
## 4.2 页面树：目标应对标 Wolai / Notion
|
||
|
||
这里的“对标”不是纯视觉复刻，而是对标：
|
||
|
||
- 页面层级表达方式
|
||
- hover 操作节奏
|
||
- 新建 / 展开 / 拖拽 / 上下文动作的一致性
|
||
- 页面树作为知识库导航入口的轻量感
|
||
|
||
### 当前已经具备的部分
|
||
|
||
- 已有页面树 projection 主链
|
||
- 已有基础展开 / 新建 / 重命名 / 上下移动作
|
||
- 已有主站切流挂载位
|
||
|
||
### 当前缺失的关键能力
|
||
|
||
- 缺少 hover 暴露的轻量动作区
|
||
- 缺少更细的页面类型 / 状态表达
|
||
- 缺少更自然的层级拖拽交互
|
||
- 缺少键盘导航与 focus 管理
|
||
- 缺少右键菜单与上下文操作体系
|
||
- 缺少行级局部状态管理
|
||
- 缺少高密度列表的稳定渲染与滚动体验
|
||
- 缺少与搜索、跳转、最近访问状态的联动边界
|
||
|
||
### 当前与 Wolai / Notion 的本质差距
|
||
|
||
当前新壳更像：
|
||
|
||
- “展示树数据并支持几个命令”
|
||
|
||
而 Wolai / Notion 页面树更接近：
|
||
|
||
- “低干扰导航器 + 轻量页面管理器”
|
||
|
||
所以页面树下一阶段的重心不是“增加更多按钮”，而是：
|
||
|
||
- 让操作默认隐藏、按需显现
|
||
- 让层级结构更轻
|
||
- 让拖拽、展开、新建、上下文菜单进入一致的节奏
|
||
|
||
## 4.3 Sidebar：目标不是单独对标某产品，而是成为稳定壳
|
||
|
||
在长期架构中，Sidebar 的任务不是持有树真相，而是：
|
||
|
||
- 承载 projection
|
||
- 承载搜索入口
|
||
- 承载快速切换
|
||
- 承载少量工作区级操作
|
||
|
||
所以 Sidebar 的核心问题不是“左栏长什么样”，而是：
|
||
|
||
- 树域壳与主站其它能力之间的耦合是否被切干净
|
||
|
||
当前 Sidebar 仍然偏重，说明下一阶段除了树控件本身，还要继续做：
|
||
|
||
- Sidebar 壳职责收敛
|
||
- 树域与其它面板解耦
|
||
- 搜索 / AI / 树域三者的边界整理
|
||
|
||
---
|
||
|
||
## 5. 当前代码中的具体偏差
|
||
|
||
## 5.1 `filetree` 模式闭环仍不完整
|
||
|
||
当前主站已向新壳传入 `mode=\"filetree\"`，但 Rust route 与壳内脚本对模式的识别还没有完整闭环。
|
||
|
||
这意味着当前“文件树已切到新壳”不能简单视为已经完成。
|
||
|
||
这一点必须优先修正，因为它会直接影响：
|
||
|
||
- 文件树功能判断
|
||
- 测试结果判断
|
||
- 后续重构任务拆分
|
||
|
||
## 5.2 新壳仍是协议验证页，不是产品树控件
|
||
|
||
当前树壳使用：
|
||
|
||
- 手写 HTML 模板
|
||
- 手写 DOM 生成树节点
|
||
- 手写按钮动作
|
||
|
||
这在协议验证阶段是合理的，但不应继续长期积累。
|
||
|
||
如果继续在这一层追加：
|
||
|
||
- hover 细节
|
||
- 菜单
|
||
- 多选
|
||
- DnD
|
||
- keyboard
|
||
|
||
最终只会把过渡壳演化成难维护的第二套前端。
|
||
|
||
## 5.3 旧树的成熟交互能力尚未被系统迁移
|
||
|
||
旧文件树与旧页面树中，已经沉淀出一部分成熟能力：
|
||
|
||
- 文件树的拖放反馈
|
||
- 文件树的多选与内部拖放
|
||
- 页面树的虚拟化
|
||
- 页面树的拖拽排序
|
||
|
||
这些能力现在还没有以“协议化行为模型”的方式迁移进新树域，而是仍然留在旧 React 实现里。
|
||
|
||
这意味着下一阶段不能只盯新壳，还要做一件关键工作：
|
||
|
||
- 把旧树中已经证明有效的交互经验抽象成正式产品合同
|
||
|
||
---
|
||
|
||
## 6. 下一阶段应如何指导修改
|
||
|
||
## 6.1 原则一：停止把过渡 shell 当最终实现打磨
|
||
|
||
接下来不应继续以如下方式推进：
|
||
|
||
- “再补几个按钮”
|
||
- “再修一版样式”
|
||
- “再把这个 iframe 页面做像一点”
|
||
|
||
这些动作只能缓解表面问题，不能得到产品级树控件。
|
||
|
||
正确方式是：
|
||
|
||
- 把当前壳明确标记为过渡验证层
|
||
- 只修协议、切流、阻塞性错误
|
||
- 不在这里继续堆复杂交互
|
||
|
||
## 6.2 原则二：先冻结产品交互合同，再进入 Rust Web 正式实现
|
||
|
||
下一阶段首先要做的，不是直接写更多 UI，而是冻结两份合同：
|
||
|
||
- 文件树产品交互合同
|
||
- 页面树产品交互合同
|
||
|
||
这两份合同至少应明确：
|
||
|
||
- 行模型
|
||
- 层级缩进规则
|
||
- active / selected / focused / dragging 的区别
|
||
- hover 暴露策略
|
||
- 右键菜单入口
|
||
- 键盘导航规则
|
||
- 多选规则
|
||
- 拖放语义
|
||
- 内联重命名规则
|
||
- 空白区与容器区行为
|
||
|
||
## 6.3 原则三：旧树不是要照抄，而是要提炼成熟行为
|
||
|
||
当前仓库里旧树实现仍然有直接参考价值：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/file-tree.tsx`
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/private-tree.tsx`
|
||
|
||
它们的价值不在于：
|
||
|
||
- 继续长期保留 React 版本
|
||
|
||
而在于：
|
||
|
||
- 可以作为“已在当前产品中验证过的交互基线”
|
||
|
||
下一阶段应从它们中提炼：
|
||
|
||
- 哪些交互是必须保留的
|
||
- 哪些只是过渡做法
|
||
- 哪些要升级成正式协议字段或 UI 状态机
|
||
|
||
## 6.4 原则四：文件树与页面树应共用一套树行为骨架
|
||
|
||
下一阶段不要再走两套完全独立实现。
|
||
|
||
应采用：
|
||
|
||
- 同一套 tree row model
|
||
- 同一套 selection / focus / keyboard / drag state
|
||
- 同一套 command dispatch
|
||
|
||
然后在 projection 层区分：
|
||
|
||
- `page_tree`
|
||
- `file_tree`
|
||
|
||
这样才能保持：
|
||
|
||
- 文件树不是孤立系统
|
||
- 页面树不是孤立系统
|
||
- 两者继续服从 `tree-first graph kernel`
|
||
|
||
## 6.5 原则五：最终目标应是产品级 Rust Web tree shell，而不是长期 iframe 壳
|
||
|
||
长期上，目标应当是：
|
||
|
||
- Rust Web 正式树控件
|
||
- 直接消费 projection protocol
|
||
- 直接发 command protocol
|
||
- 主站以内嵌挂载或原生整合方式承载
|
||
|
||
而不是：
|
||
|
||
- 长期保留 `iframe + postMessage + fallback` 作为正式方案
|
||
|
||
`iframe` 在当前阶段的价值是：
|
||
|
||
- 降风险切流
|
||
- 降低对主站的侵入
|
||
|
||
它不应成为最终交付形态。
|
||
|
||
---
|
||
|
||
## 7. 建议采用的参考体系
|
||
|
||
## 7.1 最值得参考：行为模型参考
|
||
|
||
优先级最高的不是某个“现成树组件”，而是行为模型参考。
|
||
|
||
推荐优先参考：
|
||
|
||
- `headless-tree`
|
||
|
||
主要借鉴内容：
|
||
|
||
- row model
|
||
- selection
|
||
- focus
|
||
- keyboard
|
||
- drag and drop 状态拆分
|
||
|
||
这类参考最适合解决：
|
||
|
||
- 为什么树一旦复杂就开始失控
|
||
- 为什么文件树与页面树经常需要重复写交互
|
||
|
||
## 7.2 产品结构参考
|
||
|
||
推荐参考：
|
||
|
||
- `AppFlowy`
|
||
- `AFFiNE`
|
||
|
||
主要借鉴内容：
|
||
|
||
- Sidebar 与页面树的产品层边界
|
||
- 工作区 / 页面 / 文档之间的协作关系
|
||
- 页面树如何作为知识产品的导航层
|
||
|
||
不建议直接借：
|
||
|
||
- 大量样式实现细节
|
||
- 与当前架构不一致的事实源模型
|
||
|
||
## 7.3 Rust Web UI 参考
|
||
|
||
推荐参考：
|
||
|
||
- `Leptos`
|
||
- `radix-leptos`
|
||
- `thaw`
|
||
|
||
主要用途：
|
||
|
||
- 实现正式 Rust Web tree shell
|
||
- 补齐 collapsible / menu / scroll area / overlay 等 primitives
|
||
|
||
## 7.4 不建议作为主导参考的对象
|
||
|
||
以下可以看，但不应成为主导路线：
|
||
|
||
- 终端树组件
|
||
- 桌面 GUI 树组件
|
||
- 纯列浏览器方案
|
||
|
||
原因是它们无法直接回答当前最核心的问题：
|
||
|
||
- 如何在 Web 主站中实现产品级页面树 / 文件树
|
||
|
||
---
|
||
|
||
## 8. 下一阶段的任务拆分建议
|
||
|
||
## 8.1 阶段 A：修正当前过渡壳中的协议闭环问题
|
||
|
||
只处理阻塞项：
|
||
|
||
- 修正 `filetree` 模式闭环
|
||
- 校正 projection / mode / consumer 对应关系
|
||
- 补齐最小测试
|
||
|
||
这一阶段不做：
|
||
|
||
- 大规模 UI 打磨
|
||
- 新交互堆叠
|
||
|
||
## 8.2 阶段 B：产出页面树 / 文件树产品交互合同
|
||
|
||
必须单独落文档，至少包含：
|
||
|
||
- 文件树对标 VS Code 的功能矩阵
|
||
- 页面树对标 Wolai / Notion 的功能矩阵
|
||
- 当前已实现 / 未实现 / 不做 的判定
|
||
- 对 projection 和 command 的新增要求
|
||
|
||
## 8.3 阶段 C：实现正式 tree row model 与状态骨架
|
||
|
||
这一阶段要优先完成：
|
||
|
||
- row model
|
||
- selection model
|
||
- focus model
|
||
- keyboard model
|
||
- drag state
|
||
- context menu entry model
|
||
|
||
这一层最好先独立，再挂 UI。
|
||
|
||
## 8.4 阶段 D：实现产品级 Rust Web tree shell
|
||
|
||
这一阶段才进入正式 UI：
|
||
|
||
- 页面树 renderer
|
||
- 文件树 renderer
|
||
- picker renderer
|
||
- 统一 shell 挂载
|
||
|
||
## 8.5 阶段 E：收敛旧树实现
|
||
|
||
最后再做：
|
||
|
||
- 旧文件树 helper 清理
|
||
- 旧页面树 helper 清理
|
||
- 旧 Sidebar 树域状态清理
|
||
- 旧 consumer 收口
|
||
|
||
---
|
||
|
||
## 9. 最终结论
|
||
|
||
当前实现与设计之间，不存在“方向性错误”，但存在明显的“阶段性落差”。
|
||
|
||
这个落差的本质不是：
|
||
|
||
- 少几个按钮
|
||
- 样式还不够像
|
||
|
||
而是：
|
||
|
||
- 当前完成的是树域过渡 shell
|
||
- 目标要求的是产品级树控件系统
|
||
|
||
因此，接下来应明确口径：
|
||
|
||
- 当前 git 中的新树实现，定义为**过渡验证层**
|
||
- 下一阶段任务，定义为**产品级树域控件重建**
|
||
|
||
只有这样，团队后续的修改方向才不会继续发散。
|