mnote/wolaiplan copy.md

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，打通「块 <-> 页面」的流转。