mnote/wolaiplan.md

# Wolai 深度复刻计划

**目标**：复刻 Wolai 在线文档的核心体验，首先补齐左侧树状侧边栏的交互稳定性，并在右侧 BlockNote 编辑器内实现官方文档列举的全部块能力、引用链路与媒体处理。
**基准**：`design/ui_react.md`、`design/PHASE_1.5_TURN_TO_PAGE_EXACT_CLONE.md`，以及 `scraped_docs` 目录内的官方说明。
**范围**：Next.js + Supabase + BlockNote 技术栈，聚焦 Web 前端与与 Supabase 表结构；暂不包含移动端或第三方 IM 集成。


## 0. 对标资料与能力映射
| 模块 | 对标文档 | 关键能力 | 当前差距 |
| --- | --- | --- | --- |
| 工作空间壳层/侧边栏 | `scraped_docs/功能概览.md`、`scraped_docs/页面定义.md`、`scraped_docs/垃圾桶.md` | 左侧树支持星标置顶/公共/共享/私有/模板/垃圾桶分区、宽度拖拽、工作空间切换、顶部功能按钮；垃圾桶需支持恢复/彻底删除及“操作确认” | 仅有简单树结构，缺分区、星标、垃圾桶操作、右键菜单及拖拽稳定性 |
| 页面配置 | `scraped_docs/页面选项.md` | 自适应宽度、小字体、标题目录、标题自动编号、编辑保护、导出/移动/嵌入/历史/统计、自定义页面默认布局 | 目前只有部分菜单；标题目录/编号、编辑保护、字数统计未实现 |
| 标题体系 | `scraped_docs/标题.md` | H1-H5、折叠标题、快捷键/Markdown/斜杠创建、标题目录关联、自动编号、居中、级别提示 | BlockNote 默认仅支持 H1-H3，无折叠、无自动编号、无快捷键转换 |
| 块编辑基础 | `scraped_docs/基本编辑.md` | 块是第一等公民：拖动、分栏、块结构显示、块转换、块级复制/粘贴/缩进、文本样式/颜色/链接/引用/显示块结构快捷键 | 现有 BlockNote 能力未进行 Wolai 样式与交互定制，缺块结构视图、块插入按钮等细节 |
| 斜杠菜单 | `scraped_docs/斜杠菜单.md` | `/` 唤起可搜索命令，覆盖基础块、进阶块、转换、行内元素、媒体、引用、快速功能、颜色/背景 | 仅有默认 BlockNote slash menu，命令内容/分组/拼音过滤未对齐 |
| 列表与待办 | `scraped_docs/数字列表.md`、`scraped_docs/todolist.md` | 多级编号格式可自定义、Markdown/快捷命令、缩进结构、进度条联动、高级待办四态及 Alt 切换取消 | 数字列表格式固定，缺高级待办、进度条联动逻辑 |
| 引用体系 | `scraped_docs/页面引用.md`、`scraped_docs/块引用.md` | [[/ # 快速引用、预引用、引用别名、行内/嵌入块引用、拖拽引用、反向链接、嵌入到...、快捷键 H/Q/Ctrl+Shift+R | 目前仅有基本页面链接，无预引用、别名、嵌入块引用、反向引用列表 |
| 搜索 | `scraped_docs/搜索选项.md` | `Ctrl/Cmd+P` 全局搜索、最近访问列表、仅标题/精确/时间范围过滤、当前页面范围过滤、图片 OCR 搜索、快捷键多窗口打开 | 只有简单页面检索，无过滤器、图片 OCR、快捷开窗 |
| 媒体/图片 | `scraped_docs/图片.md` | 上传/最近上传/链接/动态图标四入口、拖拽/粘贴、大小限制提示、对齐/边框/说明/说明居中/链接、全屏/查看原图/下载、裁剪/马赛克/绘制编辑、手动 OCR | 仅能上传图片，缺菜单操作、编辑器、OCR 入口、动态图标 |

## 1. 现状分析与问题定位
### 1.1 导航与工作空间壳层
- 树状结构拖拽存在抖动与状态不同步，缺少 Wolai 官方的分区/折叠/右键菜单/星标/垃圾桶功能。
- 顶部功能按钮（搜索、页面关系图、导入、成员等）未复刻，空间切换流程也不符合 `功能概览.md` 描述。

### 1.2 编辑器交互
- BlockNote 默认样式与 Wolai 蓝色系(#2563eb)相差较大，行距、列布局、块菜单体验不足。
- H5-H9、折叠标题、标题目录/编号、块转换、显示块结构等官方能力缺失。
- 待办、进度条、数字列表等块尚未实现 Wolai 规则，`转为页面` 功能仍未闭环。

### 1.3 引用、搜索与上下文
- 目前无 [[ 预引用、别名、嵌入引用等；页面引用未形成反向链接、也没有“嵌入到...”工作流。
- 全局搜索停留在基础 Title 匹配层面，缺时间范围过滤、图片 OCR 建索引、快捷键打开多窗。

### 1.4 媒体与垃圾桶
- 图片块只支持最小上传，暂无编辑、说明、链接、OCR 和动态图标；无法区分最近上传。
- 垃圾桶界面缺“操作确认”开关、搜索与恢复/彻底删除功能，风险不可控。

## 2. 分阶段路线图
### 阶段 A：侧边栏与空间壳层重构（T+3 天）
- [x] 新建 `SidebarTree` 数据层，按工作空间/公共/共享/私有/星标/模板分类读取 Supabase；对齐 `功能概览.md` 的折叠状态与宽度拖拽。
- [x] 引入 `@dnd-kit` 实现虚拟化拖拽，保证无限嵌套无抖动；补齐右键菜单（重命名/移动/删除/转为子页面）。
- [x] 实现顶部功能按钮占位与事件（搜索入口、页面关系图、导入、成员、消息箱、今日速记、手气不错、更多）。
- [x] 垃圾桶列表、恢复/彻底删除、操作确认、关键字搜索全部落地。

### 阶段 B：编辑器块体系与标题/列表（T+5 天）
- [x] 以 `scraped_docs/基本编辑.md` 为准对 BlockNote 主题进行定制：块拖拽手柄、上下插入按钮、列布局、显示块结构。
- [x] 完成 H1-H5、折叠标题、标题居中/快捷键/自动编号、标题目录与右侧 TOC。
- [x] 实现数字列表格式层级选择、Markdown 快捷输入、进度条块与高级待办四态以及进度联动。
- [x] 补齐 `/` 命令面板、拼音过滤、命令分组、快速功能入口以及颜色/背景命令。

### 阶段 C：页面/块引用与搜索体系（T+4 天）
- [x] [[ / # 预引用流水线与引用面板基础版：BlockNote 双输入触发搜索面板，`useReferenceComposer` 负责调用 `/api/references/record`，并将行内/嵌入引用写入新建的 `page_refs` 表；底部提供 `PageBacklinksPanel` 读取 `list_backlinks` RPC 并展示反向引用列表。  
  - [x] 服务端：创建 `page_refs` 表 + 触发器/策略，提供 `record_page_ref`、`list_backlinks` RPC，并通过 API 路由对齐工作空间鉴权。  
  - [x] 前端：`SearchPalette` 引入 `useReferenceComposer`，自动写入引用并回填 blockId；`DocumentContent` 新增反链面板。  
  - [x] 进阶：`PageHoverCard` 引用预览、拖拽引用卡片、`嵌入到...`、`复制块引用` 快捷入口与引用筛选折叠仍待实现。  
- [x] 搜索弹窗（Ctrl/Cmd+P）与 OCR 过滤：复刻 Wolai 快捷搜索，支持最近访问缓存、仅标题 / 精确匹配 / 编辑时间 / 创建时间 / 当前页面范围 / 图片 OCR 多过滤器，并提供 Ctrl/Cmd+Enter 新开窗口、Alt+Enter 右侧打开。  
  - [x] 数据：落地 `user_recent_pages` 表 + `/api/search/recent`，`/api/search/documents` 同时返回最近访问并在前端展示。  
  - [x] UI：提供最近/全部 Tab、编辑/创建时间切换、自定义日期选择及 OCR 过滤提示。  
  - [x] 验证：补充 vitest 针对过滤组合（仅标题+时间范围）、快捷键映射（Ctrl/Cmd+Enter、Alt+Enter）以及 OCR 结果高亮。  
- [x] 页面选项与统计：自适应宽度/小字体/标题目录/编辑保护/导出/历史/字数统计等全部可在右上角菜单内切换，并同步到 Supabase。  
  - Schema：`pages` 表新增 `is_narrow_width`, `use_small_font`, `toc_mode`, `is_locked`, `stats_word_count`, `stats_todo` 字段；新增 `page_audit_logs` 记录导出/历史访问。  
  - 交互：`PageOptionsDrawer` 组件统一渲染切换项，部分操作（导出、历史）通过 Server Action 调用 Supabase Edge Function；字数/待办统计依赖块结构 diff 即时刷新并展示在面板底部。  
  - 安全：编辑保护开启后 BlockNote 进入只读状态，界面显示锁标识并要求拥有者解锁，所有写入请求需校验 `pages.is_locked`。

### 阶段 D：媒体与增值体验（T+3 天）
- [x] 图片块：上传/最近上传/链接/动态图标四入口，尺寸限制校验，菜单中支持边框/说明/说明居中/超链接/全屏/查看原图/下载/替换/编辑/OCR。
- [x] 图片编辑器集成裁剪、矩形、马赛克、自由绘制；OCR 操作触发 Supabase Edge Function 建索引供搜索使用。
- [ ] 模板中心/帮助入口、空间功能按钮埋点、Good Night 模式跟随系统等 UI 细节收尾。

## 3. 关键模块实现要点
### 3.1 侧边栏与工作空间（来源：`功能概览.md`、`页面定义.md`、`垃圾桶.md`）
- 列表以顶层页面为根，支持无限展开+懒加载；同级采用虚拟滚动避免渲染开销。
- 星标置顶、公共/共享/私有/模板中心入口需可切换并记忆折叠状态；垃圾桶内可按标题搜索并展示“操作确认”开关。
- 工作空间下拉展示所有空间，允许创建/加入并一键切换；顶部功能按钮根据空间类型（团队/个人）切换文案。

### 3.2 页面容器与选项（来源：`页面选项.md`）
- 页面右上角菜单包含：自适应宽度、小字体、标题目录/编号、编辑保护、撤回、删除、移动、嵌入、模板、复制链接（含标题）、行内/嵌入引用、导出、页面历史、字数统计、待办统计。
- 自定义页面弹窗可调整字体、布局、显示块引用数字、折叠反向引用、隐藏子页面、嵌入默认位置。
- 标题目录宽度需根据视口自适应，提供完整/精简/折叠菜单和 `Ctrl/Cmd+Shift+L` 快捷键。

### 3.3 标题系统（来源：`标题.md`）
- 支持 `/h1`-`/h5`、`+##` 折叠标题、`Ctrl/Cmd+Shift+1~4` 快捷键、`+` 转折叠，标题悬浮显示等级圆点。
- 自动编号校验层级并以红色问号提示错误；编号点击可切换样式或关闭。
- 标题可居中（块菜单/`C` 键），并与标题目录联动展示子页面。

### 3.4 块编辑与斜杠菜单（来源：`基本编辑.md`、`斜杠菜单.md`）
- 左侧 `::` 手柄支持拖动、上下/左右插入（+ 按钮、A/B 快捷键），`Esc` 选中块，`Ctrl/Cmd+A` 二段选择，`Tab/Shift+Tab` 缩进。
- 块结构视图通过 `Ctrl/Cmd+Shift+U` 开关灰色虚线框；块菜单含“转换为”并列出所有文本类块。
- 斜杠命令按官方分组（基础块/进阶块/转换/行内元素/媒体/引用/快速输入/分栏/快速功能/颜色/背景），支持拼音模糊与英文过滤；命令项需展示快捷键或描述。

### 3.5 列表与待办（来源：`数字列表.md`、`todolist.md`）
- 数字列表默认三层（1/a/i）循环，并允许通过层级首项菜单切换样式；处理跨块断裂和图片缩进造成的编号断层。
- 待办列表支持 Markdown `[]`、高级待办 `()`、折叠变体 `+[]`、`+()`，进度条块读取同级待办完成度，高级待办 Alt/Opt 点击直接切换为取消。
- 待办完成度同步页面选项中的统计信息。

### 3.6 页面/块引用（来源：`页面引用.md`、`块引用.md`）
- 输入 `[[` / `#` / 文本样式 / `Ctrl/Cmd+Shift+R` 统一本地化搜索；若无命中提供“预引用”和“创建页面”。
- 行内/嵌入引用可通过 `复制块引用链接` (H/Q 快捷键) 或拖拽到右侧边栏创建；行内引用可设置别名并悬浮预览。
- 页面底部展示反向引用列表并支持折叠（配合页面选项中的折叠引用设置）。

### 3.7 搜索与工作流（来源：`搜索选项.md`）
- 搜索弹窗默认显示最近 20 个页面，可清空记录；输入时支持模糊匹配标题、分词匹配内容，英文/数字前缀匹配。
- 过滤器：仅匹配标题、精确匹配、编辑时间、创建时间、当前页面范围、图片 OCR；回车打开，`Ctrl/Cmd+Enter` 新窗口，`Alt/Opt+Enter` 右侧边栏。
- 选中文本 `Ctrl/Cmd+P` 直接填充搜索词。

### 3.8 媒体/图片（来源：`图片.md`）
- `/tp` 插入图片后提供上传/最近上传/链接/动态图标；支持多文件拖拽上传、粘贴图片/链接。
- 图片块菜单包含边框、默认大小、全屏、查看原图、下载、更换、说明、说明居中 (`C`)、添加链接。
- 图片编辑器提供裁剪/矩形/马赛克/自由绘制，OCR 操作会触发后台任务并有状态提示；说明区可输入文本并选择对齐方式。
- 动态图标能力需可选择日期/百分比/字符等变体。

### 3.9 垃圾桶与安全（来源：`垃圾桶.md`）
- 左侧底部固定“垃圾桶”入口，支持搜索、恢复、彻底删除；提供“操作确认”开关及 180 天恢复提示。
- 恢复页面默认回到“我的页面”，彻底删除需在 Supabase 端调用软删除 / 标记以便后台恢复。

## 4. 技术规范
- **技术栈**：Next.js 15 App Router、React 18.3、Supabase（Auth + Postgres + Storage）、BlockNote + Tiptap 扩展、Tailwind CSS v4、`lucide-react`/`react-icons`。
- **状态管理**：`zustand` 统一管理全局 UI（Sidebar/Dialogs/Theme），`@tanstack/react-query` 管理数据 fetching 与缓存；搜索/引用使用 React Server Actions + Supabase RPC 提升性能。
- **拖拽与虚拟化**：`@dnd-kit/core` + `@dnd-kit/sortable`，虚拟树使用 `@tanstack/react-virtual`，结合稳定 ID 解决嵌套节点闪动。
- **样式要求**：全局遵循 Wolai 配色与排版，标题、待办、列表等组件以 CSS 变量驱动，支持 Good Night 模式与系统跟随。
- **编码规范**：所有字符串/文件 UTF-8、中文注释；公共逻辑拆入 `services/` 或 `src/lib/`，组件使用 `src/components/wolai/*` 组织。
- **Supabase 表设计**：
  - `pages`（层级/排序/图标/题头图/保护状态）；
  - `blocks`（类型/属性 JSON/父子顺序/引用 ID）；
  - `media_assets`（文件/最近上传/动态图标配置/OCR 文本）；
  - `page_refs`（引用关系、别名、行内/嵌入标记）。

## 5. 验证计划
### 自动化测试
- `supabase/functions`：添加单元测试验证 OCR 索引写入、垃圾桶恢复逻辑。
- 前端 `vitest`：
  - Sidebar 拖拽排序、星标过滤、垃圾桶操作确认。
  - Block schema：标题转换/折叠、待办进度联动、转为页面数据写入。
  - Slash menu：命令过滤（拼音/英文）、命令执行回调。
- E2E（Playwright）：
  1. 新建页面 -> 输入 `/h5` -> 自动编号 -> 打开标题目录。
  2. 创建高级待办 + 进度条 -> Alt 点击取消 -> 进度更新。
  3. 复制块引用 -> 粘贴为嵌入 -> 搜索引用的别名。
  4. 上传图片 -> 编辑 -> 启动 OCR -> 通过搜索定位。

### 手动验证清单
- 侧边栏：三层嵌套创建/拖拽/移动到垃圾桶/恢复；星标页面固定在顶部。
- 编辑器：`转为页面` 保留嵌套内容；折叠标题展开/折叠一致；显示块结构/Good Night 切换。
- Slash menu：`/tp`、`/dblb`、`/zhwlb`、`/grsz` 等命令可被拼音缩写过滤。
- 搜索：键入中文模糊、英文前缀、仅标题、编辑时间过滤；`Ctrl+Enter` 新窗口、`Alt+Enter` 右侧打开。
- 引用：`[[` 预引用 -> 创建新页面 -> 切换别名 -> 页面底部显示反向引用；`嵌入到...` 将块嵌入其他页面。
- 图片：上传 + 最近上传选择 + 链接插入 + 动态图标，OCR 后在搜索中出现高亮摘要。
- 垃圾桶：打开操作确认、恢复/彻底删除操作均符合提示。

## 6. 下一步行动
1. 输出 Sidebar 数据结构与拖拽方案设计稿，确定 Supabase 表/索引需求。
2. 基于 `scraped_docs/基本编辑.md` 构建 BlockNote 自定义 schema（标题/待办/进度条/转页面），并封装 `/` 命令扩展。
3. 设计全局搜索 & OCR 索引流程（图片上传 -> Edge Function OCR -> Supabase `media_assets` 更新 -> 搜索服务），并评估性能预算。
4. 规划垃圾桶与页面历史数据清理脚本，确保 180 天内可恢复。