80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
# Wolai 深度复刻计划 (Wolai Deep Replication Plan)
|
||
|
||
**目标**：深度复刻 Wolai 的核心体验，重点解决左侧树状侧边栏的 Bug，并完善右侧编辑器的块交互（特别是「转为页面」功能）。
|
||
**基准**：严格遵循 `design/ui_react.md` 和 `design/PHASE_1.5_TURN_TO_PAGE_EXACT_CLONE.md`。
|
||
|
||
## 1. 现状分析 & 问题定位
|
||
|
||
当前项目已具备基础骨架（Next.js + Supabase + BlockNote），但在精细度和交互上仍有差距：
|
||
* **侧边栏 (Sidebar)**：
|
||
* 存在 Bug：拖拽抖动、状态同步延迟、无限嵌套渲染可能出错。
|
||
* 缺失细节：右键菜单（重命名/删除）、多选操作、精确的 Hover/Active 样式。
|
||
* **编辑器 (Editor)**：
|
||
* 缺失核心功能：「转为页面」互转逻辑。
|
||
* 样式细节：BlockNote 默认样式需定制为 Wolai 的蓝色系 (#2563eb)。
|
||
|
||
## 2. 实施路线图
|
||
|
||
### 阶段 A: 侧边栏重构与修复 (Sidebar Overhaul)
|
||
**目标**：打造丝滑、无 Bug 的无限嵌套文件树。
|
||
|
||
1. **数据层优化**：
|
||
* 确保 `documents` 表的 `parent_id` 递归查询高效（使用 Supabase recursive CTE）。
|
||
* 实现 `useSidebar` Hook，统一管理展开/折叠状态（持久化到 localStorage）。
|
||
2. **交互层重写 (dnd-kit)**：
|
||
* 使用 `@dnd-kit/core` 替换现有的拖拽逻辑（如果现有不稳定）。
|
||
* **解决抖动**：实现 `DragOverlay`，确保拖拽时有清晰的半透明快照。
|
||
* **精确落点**：实现 "Drop Indicator"（蓝色横线），明确显示是「插入中间」还是「变为子节点」。
|
||
3. **UI 细节复刻**：
|
||
* **样式**：行高 28px，字体 14px Inter，Hover 背景 `#f5f5f5`，选中背景 `#eef2ff` + 左侧蓝条。
|
||
* **图标**：使用 `lucide-react`，文件夹折叠/展开箭头动画（90度旋转）。
|
||
* **右键菜单**：实现自定义 Context Menu，包含：重命名、删除、在下方新建页面、复制链接。
|
||
|
||
### 阶段 B: 编辑器深度定制 (Editor Refinement)
|
||
**目标**：实现 Wolai 的「块即页面」核心体验。
|
||
|
||
1. **样式定制**：
|
||
* 覆盖 BlockNote 默认 CSS 变量，使用 Wolai 蓝色 `#2563eb` 作为主色（光标、选区、链接）。
|
||
* 调整块间距（margin-bottom: 8px）和内边距。
|
||
2. **功能：转为页面 (Turn to Page)**：
|
||
* **后端 API**：实现 `POST /api/documents/create-child`，接收块内容，创建子文档。
|
||
* **自定义块**：注册 `PageReference` 块，渲染为蓝色带图标的链接块。
|
||
* **菜单集成**：
|
||
* **Side Menu (:::)**：添加「转换为 -> 页面」选项。
|
||
* **Slash Menu (/)**：添加「页面」选项。
|
||
* **双向同步**：确保在编辑器中创建子页面后，左侧侧边栏实时更新显示。
|
||
|
||
### 阶段 C: 全局交互与细节
|
||
1. **面包屑导航**：确保点击面包屑能正确跳转，并与侧边栏选中状态同步。
|
||
2. **Loading 状态**：页面切换时的顶部进度条（NProgress 风格，蓝色）。
|
||
3. **空状态**：新页面显示「无标题」占位符和「按 / 输入命令」提示。
|
||
|
||
## 3. 技术规范 (Strict Guidelines)
|
||
|
||
* **CSS 框架**：Tailwind CSS (v4)。
|
||
* **图标库**：`lucide-react` (通用), `react-icons` (特定品牌)。
|
||
* **状态管理**：`zustand` (全局 UI 状态), `swr` / `react-query` (数据获取)。
|
||
* **拖拽库**：`@dnd-kit/core`, `@dnd-kit/sortable` (推荐，比 react-dnd 更现代且易于控制样式)。
|
||
|
||
## 4. 验证计划
|
||
|
||
### 自动化测试
|
||
* (暂无，依赖手动验证)
|
||
|
||
### 手动验证清单
|
||
1. **侧边栏测试**：
|
||
* [ ] 创建 3 层嵌套页面，确认缩进正确。
|
||
* [ ] 拖拽页面 A 到页面 B 内部，确认无刷新实时更新。
|
||
* [ ] 快速展开/折叠多个节点，确认无卡顿。
|
||
* [ ] 右键重命名页面，确认编辑器顶部标题同步更新。
|
||
2. **编辑器测试**：
|
||
* [ ] 输入文本，点击左侧 `:::`，选择「转换为页面」。
|
||
* [ ] 确认原文本块变为蓝色链接块。
|
||
* [ ] 点击链接块，跳转到新页面，内容已迁移。
|
||
* [ ] 检查左侧侧边栏，确认新页面出现在原页面下方。
|
||
|
||
## 5. 下一步行动 (Next Steps)
|
||
|
||
建议优先执行 **阶段 A (侧边栏)**，因为它是整个应用的导航骨架，Bug 最影响体验。
|
||
然后执行 **阶段 B**，打通「块 <-> 页面」的流转。
|