130 lines
3.1 KiB
Markdown
130 lines
3.1 KiB
Markdown
|
# [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 或待删除对象
|