137 lines
7.7 KiB
Markdown
137 lines
7.7 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. **数据层优化**：
|
|||
|
|
## 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 的无限嵌套文件树。
|
|||
|
|
|
|||
|
|
1. **数据层优化**：
|
|||
|
|
## 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 自动格式化**：输入 `* ` 自动变列表，`# ` 变标题，`[] ` 变待办，`()` 变高级待办，`+[]` 变折叠待办。
|
|||
|
|
* **引用系统 (Reference System)**：
|
|||
|
|
* **块引用 (Block Ref)**：
|
|||
|
|
* **行内引用**：`[[` 或 `# ` 触发。虚线下划线，不可编辑，点击跳转。快捷键 `Esc` -> `H`。
|
|||
|
|
* **嵌入引用**：独立块，左侧虚线边框，可编辑（有限制）。快捷键 `Esc` -> `Q`。
|
|||
|
|
* **页面引用 (Page Ref)**：
|
|||
|
|
* **双向链接 (Backlinks)**：页面底部显示“反向引用”列表。
|
|||
|
|
* **预引用**：引用不存在的页面时，可创建“预引用”占位符或直接新建页面。
|
|||
|
|
* **聚合应用**：如 `[[TODO]]` 标签聚合。
|
|||
|
|
* **页面选项 (Page Options)**：
|
|||
|
|
* **宽屏模式**：切换定宽 (760px) / 自适应宽度。
|
|||
|
|
* **小字体**：16px -> 14px 全局缩放。
|
|||
|
|
* **标题目录 (TOC)**：右侧悬浮，层级 H1-H4 + 子页面。
|
|||
|
|
* **统计**：字数统计、块数统计。
|
|||
|
|
* **待办列表 (Todo List)**：
|
|||
|
|
* **进度条联动**：父块为进度条时，自动计算子待办块的完成百分比。
|
|||
|
|
* **高级待办**：4种状态（未做、进行中、完成、取消）。`Alt+Click` 切换取消。
|
|||
|
|
* **图片 (Image)**：
|
|||
|
|
* **插入**：命令、拖拽、复制、URL。
|
|||
|
|
* **OCR**：需手动在菜单中点击“文字识别”以建立索引。
|
|||
|
|
* **编辑**：支持裁剪、马赛克、绘图。
|
|||
|
|
|
|||
|
|
### 手动验证清单
|
|||
|
|
* **隐式 OCR**：官方文档未强调 OCR 功能，印证了其作为后台搜索索引服务的定位，而非前台核心编辑功能。
|
|||
|
|
* **文件预览**：依赖第三方服务或浏览器原生能力，保持轻量化。
|
|||
|
|
|
|||
|
|
### 手动验证清单
|
|||
|
|
1. **侧边栏测试**：
|
|||
|
|
* [ ] 创建 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` 在应用内直接渲染，提供更好的阅读体验。
|
|||
|
|
- **功能**：翻页、缩放、下载。
|
|||
|
|
|
|||
|
|
## 5. 下一步行动 (Next Steps)
|
|||
|
|
|
|||
|
|
建议优先执行 **阶段 A (侧边栏)**，因为它是整个应用的导航骨架，Bug 最影响体验。
|
|||
|
|
然后执行 **阶段 B**，打通「块 <-> 页面」的流转。
|