mnote/design/design3.0.md

# 开发集成笔记、思维导图、OCR 和 AI 问答软件的全面蓝图（v3.0 — 前后端分离 + MinerU + LightRAG 版）

**目标**：深度复刻 Wolai 的块编辑体验 + MindManager 级别的思维导图 + Supabase 在线实时协作 + 高精度 MinerU OCR + 基于 LightRAG 的知识图谱 + 向量双模检索 AI 问答，形成真正的「统一工作流」生产力工具。

**当前版本日期**：2025 年 11 月 17 日  
**核心变更摘要（给 AI 编码助手直接看）**：
- 彻底前后端分离：前端纯 Next.js 网页（零重计算），所有 OCR、向量化、知识图谱构建全部后端 Python 完成
- OCR 更换为 MinerU（精度最高、尤其中文支持完美，已在 2025 年成为 PDF 提取事实标准）
- RAG 系统更换为 LightRAG（性能/成本/精度三者最优，支持 KG + Vector 混合检索，纯 Python，原生支持 pgvector）
- 重计算任务全部后台队列化（Celery + Redis），杜绝实时阻塞，支持任务优先级与并发限制
- 客户端只负责 UI + 实时协作 + 轻量查询，前端首屏 < 800ms，编辑零卡顿

## 0. 全新架构总览（必须严格遵守）

| 组件         | 技术栈                              | 职责                                                                 | 部署方式                  |
|--------------|-------------------------------------|----------------------------------------------------------------------|---------------------------|
| 前端         | Next.js 15 App Router + TypeScript + Tailwind + shadcn/ui | UI、BlockNote 编辑器、实时协作（Yjs + Supabase Realtime）、轻量 AI 问答调用 | Vercel / Cloudflare Pages |
| 后端         | FastAPI (Python 3.11+) + LightRAG + MinerU + Celery + Redis | PDF/文件 OCR、文本提取、知识图谱构建、向量/图混合检索、后台任务队列、AI 问答接口 | Railway / Fly.io / Docker 自部署（推荐与自托管 Supabase 同机） |
| 数据库/存储   | Supabase（托管或自托管 Docker）+ pgvector + Storage + Realtime + Redis（队列） | 文档树、块内容、向量、知识图谱实体/关系（LightRAG 可直接操作 pgvector） | 自托管推荐（隐私 + 成本）   |
| 认证         | Supabase Auth（JWT）                 | 前后端共享同一 auth，FastAPI 使用 supabase-py 验证 JWT               | —                         |
| 实时协作     | Supabase Realtime + Yjs @hocuspocus/provider | 多人光标、并发编辑（只针对笔记内容，不涉及 RAG）                     | —                         |

**数据流关键路径（给 Codex/Claude 直接复制的 Prompt 用）**：
1. 用户上传 PDF → 前端上传 Supabase Storage → 调用后端 `/api/v1/tasks/ocr`（传 file_url + document_id）
2. 后端放入 Celery 队列 → Worker 执行 MinerU → 得到高质量 Markdown/JSON → 存回 document.content + 触发 LightRAG.update_index(document_id, text)
3. 用户保存笔记 / 上传文件 → 触发 LightRAG incremental update（只更新增量 chunk）
4. 用户 AI 问答 → 前端调用后端 `/api/v1/chat` → LightRAG.query(query, user_id) → 流式返回带来源引用

## 1. 功能拆解（最终验收标准保持不变，仅实现路径调整）

| 模块          | 核心功能                                      | 验收标准（可直接写测试用例）                              | 实现位置 |
|---------------|-----------------------------------------------|-----------------------------------------------------------|----------|
| 笔记          | 块编辑器、嵌套页面、双向链接、模板、斜杠命令   | 可无限嵌套、可拖拽排序、实时多人光标、斜杠命令完整         | 前端     |
| 思维导图      | 拖拽节点、折叠分支、自定义样式、双向同步笔记  | 导图修改 ↔ 笔记大纲实时同步，可导出 PNG/PDF/Markdown      | 前端     |
| 在线查看/协作 | 实时同步、共享链接、权限控制、公共只读页      | 延迟 < 800ms，支持 20 人同时编辑无明显冲突                 | 前端 + Supabase |
| 文件 OCR      | PDF/图片上传 → MinerU 高精度提取 → 自动成笔记块 | 中英文混排准确率 > 97%（2025 年 MinerU v2+），进度条 + 重试   | 后端队列 |
| AI 问答       | LightRAG（KG + Vector 混合）+ GPT-4o 流式回答 | 回答必须带来源引用，支持多跳推理、总结、对比等复杂任务         | 后端     |

## 2. 最终技术栈（2025 年 11 月 17 日最新推荐）

| 层级          | 选型                                      | 理由（2025 年实测）                                      | 关键集成点 |
|---------------|-------------------------------------------|----------------------------------------------------------|------------|
| 前端框架      | Next.js 15（App Router + RSC）            | 依旧最强，RSC 可直接调用后端 API，首屏极快               | — |
| UI/样式       | Tailwind + shadcn/ui + Radix + lucide-react | 保持不变，直接 `npx shadcn@latest add`                    | — |
| 笔记编辑器    | @blocknote/react + @blocknote/core（免费版足以）| 已验证与 Yjs + hocuspocus + Supabase Realtime 最稳定     | 前端 |
| 思维导图      | @xyflow/react (React Flow 11+)            | RSC 友好，自定义节点最强                                 | 前端 |
| 后端框架      | FastAPI + Uvicorn + Celery[redis] + Redis | 最高性能 Python Web 框架，Celery 队列成熟                | 后端 |
| OCR           | MinerU (opendatalab/MinerU latest)        | 2025 年 PDF 提取精度最高（尤其数学公式、表格、中文）     | 后端 |
| RAG / KG      | LightRAG（latest）+ pgvector              | 支持 KG + Vector 混合检索最强，增量更新极快，成本最低       | 后端，直接操作同一 Supabase pgvector 表 |
| 队列          | Celery + Redis（Upstash Redis 兼容）       | 任务优先级、失败重试、并发限制（默认 max 3 个 OCR 任务） | 后端 |
| 其他 Python 包 | mineru, lightrag, pgvector-python, supabase-py, python-dotenv, langchain-openai（仅用于调用 GPT） | 全部 2025-11 最新版                                      | — |

## 3. 数据库表结构（新增任务队列表）

```sql
-- 文档树（保持不变）
create table documents (
  id uuid primary key default uuid_generate_v4(),
  user_id uuid references auth.users not null,
  parent_id uuid references documents(id),
  title text default '无标题',
  content jsonb default '{}',            -- BlockNote 格式
  mindmap_data jsonb,
  raw_text text,                         -- MinerU 提取后的纯文本（供 LightRAG 使用）
  index_status text default 'pending',   -- pending / processing / completed / failed
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- 后台任务表（Celery 不需要表，但我们加一张方便前端查进度）
create table background_tasks (
  id uuid primary key default uuid_generate_v4(),
  user_id uuid references auth.users,
  document_id uuid references documents(id),
  task_type text,                        -- 'ocr' | 'index'
  status text default 'pending',
  progress integer default 0,
  message text,
  created_at timestamptz default now()
);

LightRAG 会自动在 Supabase pgvector 中创建自己的表（embeddings、entities、relationships 等），我们直接复用，无需手动建。

3.1 协同表格数据面（参考 design/表格方案.md）

-- 表格元信息（与文档 1:N）
create table document_tables (
  id uuid primary key default gen_random_uuid(),
  workspace_id uuid not null references workspaces(id) on delete cascade,
  document_id uuid not null references documents(id) on delete cascade,
  title text not null default '未命名表格',
  schema jsonb not null default '{}'::jsonb,         -- 列定义/格式
  view_preferences jsonb not null default '{}'::jsonb,
  is_archived boolean not null default false,
  snapshot jsonb,
  last_synced_at timestamptz,
  created_by uuid references profiles(id) on delete set null,
  updated_by uuid references profiles(id) on delete set null,
  created_at timestamptz not null default timezone('utc', now()),
  updated_at timestamptz not null default timezone('utc', now())
);

-- 表格行级数据（大表解耦，支持 Yjs SubDoc 持久化）
create table document_table_rows (
  id uuid primary key default gen_random_uuid(),
  workspace_id uuid not null references workspaces(id) on delete cascade,
  document_id uuid not null references documents(id) on delete cascade,
  table_id uuid not null references document_tables(id) on delete cascade,
  row_index integer not null,
  row_data jsonb not null default '{}'::jsonb,       -- 单元格字典
  row_hash text,
  is_deleted boolean not null default false,
  updated_by uuid references profiles(id) on delete set null,
  created_at timestamptz not null default timezone('utc', now()),
  updated_at timestamptz not null default timezone('utc', now())
);

• workspace_id + RLS：沿用 workspace_members 策略，任何读写都需要加入同一 Workspace。
• 触发器：ensure_document_table_workspace、sync_document_table_row_meta 在写入时同步 Workspace/Document，set_*_updated_at 负责时间戳。
• 行级 diff：row_index + row_hash 提供后续优化空间，满足大表局部同步、快照/导出等需求。
• 这两张表已通过 Supabase (supabase_local) 执行创建，对应迁移 20250222_add_document_tables.sql，是 Luckysheet × Yjs × Supabase 表格 MVP 的数据面基础。

4. 分阶段实施计划（v3.0 更新版 · 含后端）

阶段	目标	核心任务	预估人天	推荐给 AI 编码助手的 Prompt 示例
0	项目骨架	前端 Next.js + Supabase 初始化 后端 FastAPI + Celery + Redis + LightRAG 模板	2 天	“Create a Next.js 15 App Router project with Supabase auth + shadcn/ui AND a separate FastAPI project with Celery+Redis queue, supabase-py client, MinerU, LightRAG initialized to use pgvector.”
1	前端 Wolai 核心 + 实时协作	递归侧边栏 + BlockNote + Yjs + Supabase Realtime（参考 ui_react.md 严格实现）	5-7 天	“Build full Wolai-like document tree sidebar + BlockNote editor with real-time collaboration using @hocuspocus/provider and Supabase Realtime. Follow ui_react.md 所有样式必须 100% 复刻。”
2	后端基础 API + MinerU OCR 队列	文件上传 → Storage → 调用 /tasks/ocr → Celery worker 执行 MinerU → 更新 document.raw_text + index_status	3-4 天	“FastAPI endpoint that accepts Supabase signed URL, downloads PDF, runs MinerU magic_pdf(..., ocr=True), saves markdown to document.content and raw_text, updates index_status.”
3	LightRAG 索引管道	笔记保存或 OCR 完成 → Celery 任务 LightRAG.index(document_id, text, user_id)（增量更新）	3 天	“Use LightRAG with PGVectorStore, implement incremental update when document.updated_at changes, support user-level isolation.”
4	AI 问答侧边栏（流式）	前端调用后端 /chat stream → LightRAG.query() → SSE 返回带来源引用	2-3 天	“FastAPI SSE endpoint /api/v1/chat that uses LightRAG.query(query, user_id) and streams token + sources.”
5	思维导图 + 双向同步	React Flow + 与 BlockNote outline 实时同步	3 天	同 v2.0
6	任务进度实时推送	Supabase Realtime 监听 background_tasks 表变化 → 前端显示进度条	1 天	—
7	性能优化 + 测试 + 部署	前端 skeleton + lazy，后端 rate limit + concurrency=3，Cypress + pytest	4 天	—

总预估：单人全职 4-5 周（得益于前后端分离 + MinerU/LightRAG 开箱即用，实际比 v2 更快）

4.1 表格方案专项里程碑（摘自 design/表格方案.md）

阶段	目标	关键任务	产出 / 验收
P0 需求巩固	明确体验 & 数据需求	共识 Luckysheet 交互、BlockNote 预览范围、列类型 MVP、AI/MinerU 接口	PRD + 交互稿
P1 数据面准备	建 Supabase 表 & API	执行 SQL（见 3.1）、配置 RLS、FastAPI 新增 /tables /tables/{id}/rows CRUD、单测	后端分支 + Swagger
P2 Yjs/Luckysheet 骨架	协同内核跑通	引入 @dream-num/luckysheet、luckysheet-yjs-binding，实现 <LuckysheetProvider> 与独立编辑页	协同 demo（多端无冲突）
P3 BlockNote 表格块 & 预览	文档内插入/缩略展示	Slash 命令、自定义 block schema、预览组件（前 5 行 + hover toolbar）、BlockNote ↔ Supabase 建删同步	文档里可插入并跳转全屏
P4 全屏编辑器 & 工具栏	飞书式编辑体验	<FullScreenTableEditor>、合并/冻结/条件格式/基础公式、协作者状态、暗黑模式	500×50 表格流畅，工具栏齐全
P5 持久化 & 性能	数据安全 & 优化	SubDoc → Supabase 节流、行级 diff、定时写入 table_versions 快照、预览虚拟滚动	重连不丢数据、大表不卡顿
P6 高级扩展	导入导出 & AI	CSV/Excel 导入导出、MinerU OCR 写表、表格引用共享、权限 UI、E2E 测试	导入导出/AI 流程验证通过

上述阶段与 v3.0 总体里程碑并行推进，优先完成 P0-P4 组成表格 MVP，再与 MinerU / LightRAG 联动。

5. 常见陷阱与解决方案（2025-11 最新）

陷阱	解决方案
MinerU OCR 耗时长（大 PDF >100 页）	Celery concurrency 限制 3 + 优先级队列（OCR 高优先）+ 进度实时推送
LightRAG 首次全量索引慢	首次启动时加 --init-index 参数后台全量重建，只在生产环境跑一次
前后端跨域 + 认证	前端携带 Supabase JWT → 后端使用 supabase-py 验证 token.user_id
Supabase Storage 签名 URL 过期	后端使用 service_role key 下载（安全，普通用户只能生成短时 signed URL
LightRAG 多租户隔离	每个 user_id 建立独立 index name（如 user_{user_id}）或使用 LightRAG 的 namespace 功能
Redis 在 Vercel 无状态环境	推荐 Railway / Fly.io + Upstash Redis（兼容 Celery）

6. 立即启动命令（2025-11-17 最新）

# 前端
npx create-next-app@latest wolai-frontend --ts --app --eslint --tailwind --src-dir --import-alias "@/*"
cd wolai-frontend
npx shadcn@latest init

# 后端
python -m venv venv && source venv/bin/activate
pip install fastapi uvicorn[standard] celery[redis] redis lightrag mineru supabase-py python-dotenv pgvector openai
# 创建 app/main.py + celery -A app.celery worker --loglevel=info

结论：此 v3.0 架构彻底解决客户端卡顿、OCR 精度、RAG 成本三大痛点，MinerU + LightRAG 组合在 2025 年实测是中文知识库最强方案，强烈推荐立即执行。

编码愉快！