7.9 KiB
7.9 KiB
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 的无限嵌套文件树。
- 数据层优化：
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. 验证计划
自动化测试
- (暂无，依赖手动验证)
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 的无限嵌套文件树。
- 数据层优化：
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. 验证计划
自动化测试
- (暂无，依赖手动验证)
官方操作策略 (Official Operational Strategies)
- 块操作逻辑：
- 转换 (Turn into)：核心逻辑是“保留内容，改变形式”。通过
::菜单、快捷键或/菜单触发。 - 层级 (Hierarchy)：
- 缩进：使用
Tab/Shift+Tab控制缩进，建立父子关系。 - 嵌套：拖拽块到另一个块的内部（下方缩进位）可创建嵌套结构。
- 缩进：使用
- 布局 (Layout)：通过拖拽块到左右边缘（显示垂直蓝线）创建分栏。支持
/2等快捷指令。 - 多选 (Multi-select)：支持鼠标框选或
Shift+Click连续选择。Esc选中当前块，Shift+Arrow多选。 - Markdown 自动格式化：输入
*自动变列表，#变标题，[]变待办，()变高级待办，+[]变折叠待办。
- 转换 (Turn into)：核心逻辑是“保留内容，改变形式”。通过
- 引用系统 (Reference System)：
- 块引用 (Block Ref)：
- 行内引用：
[[或#触发。虚线下划线，不可编辑，点击跳转。快捷键Esc->H。 - 嵌入引用：独立块，左侧虚线边框，可编辑（有限制）。快捷键
Esc->Q。
- 行内引用：
- 页面引用 (Page Ref)：
- 双向链接 (Backlinks)：页面底部显示“反向引用”列表。
- 预引用：引用不存在的页面时，可创建“预引用”占位符或直接新建页面。
- 聚合应用：如
[[TODO]]标签聚合。
- 块引用 (Block Ref)：
- 页面选项 (Page Options)：
- 宽屏模式：切换定宽 (760px) / 自适应宽度。
- 小字体：16px -> 14px 全局缩放。
- 标题目录 (TOC)：右侧悬浮，层级 H1-H4 + 子页面。
- 统计：字数统计、块数统计。
- 待办列表 (Todo List)：
- 进度条联动：父块为进度条时，自动计算子待办块的完成百分比。
- 高级待办：4种状态（未做、进行中、完成、取消）。
Alt+Click切换取消。
- 图片 (Image)：
- 插入：命令、拖拽、复制、URL。
- OCR：需手动在菜单中点击“文字识别”以建立索引。
- 编辑：支持裁剪、马赛克、绘图。
手动验证清单
* **隐式 OCR**：官方文档未强调 OCR 功能，印证了其作为后台搜索索引服务的定位，而非前台核心编辑功能。
* **文件预览**：依赖第三方服务或浏览器原生能力，保持轻量化。
手动验证清单
- 侧边栏测试：
- 创建 3 层嵌套页面，确认缩进正确。
- 拖拽页面 A 到页面 B 内部，确认无刷新实时更新。 - 底部：结果计数（"共 N 条匹配结果"）+ 快捷键提示（"Ctrl+Enter 新窗口打开", "Alt+Enter 右侧边栏打开"）。
- OCR 策略 (Hidden OCR)（Live Site 验证确认）：
- 机制：图片上传后，后端异步进行 OCR 识别。
- 搜索：识别的文本会被索引，支持通过关键词搜索到包含该文本的图片页面。
- 展示：默认情况下，OCR 文本不直接显示在页面上（保持页面整洁），而是作为图片的元数据存在。
- 高亮：在搜索结果摘要中，会高亮显示匹配的 OCR 文本。
- 图片块操作 (Image Block Operations)（Live Site 捕捉确认）：
- 菜单项：
- 图片边框 (Toggle)。
- 设置图片超链接...。
- 评论。
- 对齐 (左/中/右)。
- 查看原图 / 全屏查看。
- 编辑图片 (裁剪/旋转等)。
- 文字识别 (OCR) (手动触发入口)。
- 添加说明 (Caption) / 说明文字居中。
- 下载。
- 恢复默认大小。
- 替换图片...。
- 菜单项：
- 文件预览 (File View)（Live Site 捕捉确认）：
- Office 文档 (.docx, .xlsx, .pptx)：
- 策略：不自行开发渲染器，调用 Microsoft Office Online 或 Google Docs Viewer 服务。
- 实现：在新标签页打开，或使用 iframe 嵌入 Office Online 预览链接。
- 组件推荐：
react-doc-viewer(支持多种格式，自动降级) 或直接构建 Office Online URL。
- PDF 文档：
- 策略：使用
react-pdf在应用内直接渲染，提供更好的阅读体验。 - 功能：翻页、缩放、下载。
- 策略：使用
- Office 文档 (.docx, .xlsx, .pptx)：
5. 下一步行动 (Next Steps)
建议优先执行 阶段 A (侧边栏)，因为它是整个应用的导航骨架，Bug 最影响体验。 然后执行 阶段 B，打通「块 <-> 页面」的流转。