对齐 Wolai 侧栏体验并收拢设计入库

2026-04-30 16:18:54 +08:00
parent 8c895b3dc0
commit afb2a5b8a0
89 changed files with 23188 additions and 84 deletions
@@ -0,0 +1,129 @@
+# [recycle] BlockNote Migration Plan v1
+
+> 更新时间：2026-04-18
+
+## 1. 目标
+
+这份文档用于冻结从 BlockNote 主路径迁移到 Rust block editor 的最小迁移顺序。
+
+目标不是一次性删除所有旧代码，而是：
+
+- 先让主文档页默认切到新 Rust editor 壳
+- 再把 BlockNote 降到 compat/debug
+- 最后清理旧依赖和主线耦合
+
+## 2. 当前盘点
+
+当前主路径仍直接依赖下面这些入口或依赖：
+
+- `@blocknote/core`
+- `@blocknote/react`
+- `@blocknote/mantine`
+- `blocknote-editor.tsx`
+- `schema.ts`
+- `HocuspocusProvider`
+- `Yjs`
+
+主路径宿主文件主要是：
+
+- `wolai-frontend/src/components/editor/document-content.tsx`
+- `wolai-frontend/src/components/editor/blocknote-editor.tsx`
+- `wolai-frontend/src/components/editor/schema.ts`
+
+## 3. 迁移分层
+
+迁移固定分三层：
+
+- 主路径
+  由 Rust block editor 接管
+- compat
+  保留旧 BlockNote 入口，供临时回退
+- debug
+  保留最小诊断入口，帮助排障
+
+禁止继续把 BlockNote 当成默认编辑器。
+
+## 4. 内容格式迁移策略
+
+第一阶段不要求一次性消灭所有旧内容格式。
+
+固定策略如下：
+
+- 主写链以 Rust editor command 和 Rust document model 为准
+- 旧 BlockNote JSON 通过兼容 codec 读取
+- 写回时优先生成 Rust 侧统一结构
+- 必要时保留从旧格式到新格式的单向迁移适配
+
+重点对象：
+
+- 段落
+- 标题
+- list/todo
+- `pageReference`
+- `blockReference`
+- 附件和重型自定义块
+
+## 5. 入口切换顺序
+
+第一步：
+
+- 在文档页入口切到 `mnoteWebDocumentShellEnabled`
+- 默认走 `mnote-web /document`
+- 保留 `?editor=compat` 回退参数
+
+第二步：
+
+- `document-content.tsx` 继续保留为 compat 宿主壳
+- `blocknote-editor.tsx` 继续保留为 compat 编辑器实现
+
+第三步：
+
+- 新主编辑器稳定后，再把主路径对 `schema.ts`、`HocuspocusProvider`、`Yjs` 的依赖收缩到 compat/debug
+
+## 6. 依赖收敛
+
+迁移完成前后要明确区分：
+
+- 主路径是否仍依赖 `@blocknote/core`
+- 主路径是否仍依赖 `blocknote-editor.tsx`
+- 主路径是否仍依赖 `HocuspocusProvider`
+- 主路径是否仍依赖 `Yjs`
+
+最终要求：
+
+- compat/debug 允许暂时保留
+- 主路径不再依赖以上能力
+
+## 7. 风险
+
+主要风险如下：
+
+- 旧页面内容与新结构双写不一致
+- history / snapshot / TOC / stats 边界退化
+- 重型块在新主路径下缺少最小宿主能力
+- 回退入口不明确导致线上排障困难
+
+## 8. 回退策略
+
+必须保留显式回退：
+
+- 文档页参数级 compat 入口
+- 旧 BlockNote 组件继续可挂载
+- debug 场景可直接验证旧壳
+
+在没有确认新主路径稳定前，不得直接删除 compat/debug。
+
+## 9. 验收标准
+
+满足以下条件即可视为 migration v1 达标：
+
+- 主文档页默认落到新 Rust editor 壳
+- compat/debug 入口仍可独立使用
+- `blocknote-editor.tsx` 不再是默认主路径
+- `schema.ts` 不再决定默认主编辑器
+- `@blocknote/core`
+- `blocknote-editor.tsx`
+- `schema.ts`
+- `HocuspocusProvider`
+- `Yjs`
+  已被明确标记为 compat/debug 或待删除对象