mnote/recycle/design/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 天）

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

阶段 B：编辑器块体系与标题/列表（T+5 天）

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

阶段 C：页面/块引用与搜索体系（T+4 天）

• [[ / # 预引用流水线与引用面板基础版：BlockNote 双输入触发搜索面板，useReferenceComposer 负责调用 /api/references/record，并将行内/嵌入引用写入新建的 page_refs 表；底部提供 PageBacklinksPanel 读取 list_backlinks RPC 并展示反向引用列表。
  • 服务端：创建 page_refs 表 + 触发器/策略，提供 record_page_ref、list_backlinks RPC，并通过 API 路由对齐工作空间鉴权。
  • 前端：SearchPalette 引入 useReferenceComposer，自动写入引用并回填 blockId；DocumentContent 新增反链面板。
  • 进阶：PageHoverCard 引用预览、拖拽引用卡片、嵌入到...、复制块引用 快捷入口与引用筛选折叠仍待实现。
• 搜索弹窗（Ctrl/Cmd+P）与 OCR 过滤：复刻 Wolai 快捷搜索，支持最近访问缓存、仅标题 / 精确匹配 / 编辑时间 / 创建时间 / 当前页面范围 / 图片 OCR 多过滤器，并提供 Ctrl/Cmd+Enter 新开窗口、Alt+Enter 右侧打开。
  • 数据：落地 user_recent_pages 表 + /api/search/recent，/api/search/documents 同时返回最近访问并在前端展示。
  • UI：提供最近/全部 Tab、编辑/创建时间切换、自定义日期选择及 OCR 过滤提示。
  • 验证：补充 vitest 针对过滤组合（仅标题+时间范围）、快捷键映射（Ctrl/Cmd+Enter、Alt+Enter）以及 OCR 结果高亮。
• 页面选项与统计：自适应宽度/小字体/标题目录/编辑保护/导出/历史/字数统计等全部可在右上角菜单内切换，并同步到 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 天）

• 图片块：上传/最近上传/链接/动态图标四入口，尺寸限制校验，菜单中支持边框/说明/说明居中/超链接/全屏/查看原图/下载/替换/编辑/OCR。
• 图片编辑器集成裁剪、矩形、马赛克、自由绘制；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 天内可恢复。