```markdown
# 开发集成笔记、思维导图、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 最稳定     | 前端 |
| 思维导图      | simple-mind-map + 自研 KMindRenderer      | 直接复用 Wolai 风格交互，兼容现有 KMind 主题 & 快照       | 前端 |
| 后端框架      | 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`）

```sql
-- 表格元信息（与文档 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 初始化<br>后端 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    | 思维导图 + 双向同步             | 基于 simple-mind-map 的 KMindRenderer，与 BlockNote outline 实时同步、导出/预览 | 3 天    | 同 v2.0 |

> **进度提示**：simple-mind-map 渲染器已在前端切换完成，但与 BlockNote 大纲的双向同步、导出为 PNG/PDF/Markdown 以及思维导图 ↔ 笔记互跳等能力仍属于未完成事项，需要在阶段 5 内继续收敛。
| 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 最新）

```bash
# 前端
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 年实测是中文知识库最强方案，强烈推荐立即执行。

编码愉快！
```