188 lines
16 KiB
Markdown
188 lines
16 KiB
Markdown
```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 年实测是中文知识库最强方案，强烈推荐立即执行。
|
||
|
||
编码愉快！
|
||
```
|