stage0 重构指南（紧扣 design3.0 + stage0-2.0）

目标：在 1～2 天内把旧版 stage0 的单仓库项目安全迁移为前后端分离的双仓库，完整对齐 design3.0 的架构要求（前端纯 UI + 实时协作，后端承担 MinerU OCR、LightRAG 检索与 Celery 队列）。本指南将 stage0-2.0 的动作拆得更清晰，便于直接执行或交给 AI。

0. 核心验收（必须全部满足）

双仓库落地：wolai-frontend 与 wolai-backend 干净可运行，均可独立启动。
前端：Next.js 15 App Router + Supabase Auth/Realtime/Storage；无重计算逻辑；依赖精简。
后端：FastAPI + Celery(Redis) + LightRAG + MinerU；重计算异步化；Supabase JWT 校验通。
数据：Supabase 打开 uuid-ossp、vector 扩展；documents/background_tasks 表与 RLS 全部创建。
环境变量：前后端各自 .env 配齐，service_role 仅后端持有。

1. 先备份再拆分

mv wolai-clone wolai-clone-old-backup-$(date +%Y%m%d)
mkdir wolai-frontend wolai-backend

备份后再动代码，避免误删。

2. 前端脚手架（UI + 实时协作）

cd wolai-frontend
npx create-next-app@latest . \
  --typescript --tailwind --eslint --app --src-dir \
  --import-alias "@/*" --turbo --yes
npx shadcn@latest init -d

pnpm add @supabase/supabase-js @supabase/auth-helpers-nextjs \
  @supabase/auth-helpers-react @blocknote/core @blocknote/react \
  @xyflow/react yjs y-protocols @hocuspocus/provider zustand \
  @tanstack/react-query react-dropzone sonner uuid \
  @hello-pangea/dnd lucide-react

npx shadcn@latest add button card dialog toast dropdown-menu avatar \
  separator sheet input label textarea badge command popover \
  scroll-area skeleton tabs toggle drawer

pnpm remove @blocknote/mantine tesseract.js pdfjs-dist langchain \
  @langchain/openai @langchain/community neo4j-driver @neo4j/graphql

推荐目录（RSC + 轻量 API）：

src/
├── app/
│   ├── (auth)/
│   ├── (app)/
│   │   ├── documents/[id]/page.tsx          # BlockNote+Realtime
│   │   ├── documents/[id]/mindmap/page.tsx  # XYFlow
│   │   └── layout.tsx                       # Sidebar+面包屑+底栏
│   ├── api/                                 # 仅轻量 handler（上传签名等）
│   ├── globals.css
│   └── layout.tsx
├── components/   # editor/mindmap/sidebar/common/ui
├── lib/supabase/ # client.ts / server.ts
├── hooks/
└── store/

3. 后端脚手架（重计算全搬来）

cd ../wolai-backend
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

pip install fastapi "uvicorn[standard]" celery[redis] redis \
  lightrag[hf] mineru supabase-py python-dotenv pgvector openai \
  python-multipart pydantic-settings

推荐初始结构（保持与 design3.0 API 命名一致）：

app/
├── main.py          # FastAPI 入口，挂载路由，CORS
├── deps.py          # Supabase JWT 校验、DB/Redis 会话
├── router/          # /api/v1/*
│   ├── tasks.py     # POST /api/v1/tasks/ocr（入队）/progress
│   └── chat.py      # GET /api/v1/chat（SSE 流式）
├── workers/         # Celery 实现 MinerU OCR、LightRAG 索引
├── services/        # lightrag_service.py、storage_service.py 等
└── models/          # Pydantic schema

阶段 0 允许后端路由先返回占位值（但路径、参数、鉴权要对），以便前端联调不阻塞：

POST /api/v1/tasks/ocr：接收 {document_id, file_url}，当前可直接写入 background_tasks 一条 pending，返回 task_id。
GET /api/v1/chat：接受 query + document_id，可先返回固定的流式占位文本。

4. Supabase 表与 RLS（直接在 SQL Editor 执行）

create extension if not exists "uuid-ossp";
create extension if not exists vector;

create table if not exists documents (
  id uuid primary key default uuid_generate_v4(),
  user_id uuid references auth.users not null,
  parent_id uuid references documents(id) on delete set null,
  title text default '无标题',
  content jsonb default '{}'::jsonb,
  mindmap_data jsonb,
  raw_text text,
  index_status text default 'pending',
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table if not exists background_tasks (
  id uuid primary key default uuid_generate_v4(),
  user_id uuid references auth.users not null,
  document_id uuid references documents(id),
  task_type text check (task_type in ('ocr', 'index')),
  status text default 'pending',
  progress integer default 0,
  message text,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

alter table documents enable row level security;
alter table background_tasks enable row level security;
create policy "own docs" on documents for all using (auth.uid() = user_id);
create policy "own tasks" on background_tasks for all using (auth.uid() = user_id);

LightRAG 自带表（embeddings/entities/relationships）由库自动建，无需手动创建。

5. 环境变量模板

前端 .env.local

NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

后端 .env

SUPABASE_URL=https://xxxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxxxxx
REDIS_URL=redis://default:xxxx@redis.upstash.io:6379
OPENAI_API_KEY=sk-...
FRONTEND_URL=http://localhost:3000

6. 最小联通自检（阶段 0 必测）

前端 pnpm dev 正常启动，/documents/[id] 页面可加载（即便内容空白）。
后端 uvicorn app.main:app --reload --port 8000 可起，GET /health 返回 ok（请先实现简单健康检查）。
前端调用 POST /api/v1/tasks/ocr 返回 task_id，并能从 Supabase background_tasks 查询到插入记录。
RLS 验证：换用户 token 后只能看到自己的 documents/background_tasks。
Celery/Redis 启动不报错（即便任务暂未真正执行 MinerU）。

7. Git 记录（拆分后各自初始化）

cd wolai-frontend
git init && git add . && git commit -m "chore: stage0 frontend scaffold (design3.0)"
git tag -a "v0.1.0-stage0-frontend" -m "design3.0 ready"

cd ../wolai-backend
git init && git add . && git commit -m "chore: stage0 backend scaffold (design3.0)"
git tag -a "v0.1.0-stage0-backend" -m "design3.0 ready"

8. 丢给 AI 的阶段 1 Prompt（可直接复制）

你现在是一个顶级全栈工程师，要基于现有 stage0 双仓库继续实现 design3.0。前端：Next15 + Supabase + BlockNote/XYFlow，后端：FastAPI+Celery+LightRAG+MinerU。请完成：
1) 递归侧边栏（240px，@hello-pangea/dnd，无限嵌套，参考 ui_react.md 像素级复刻）。
2) /documents/[id]/page.tsx 用 BlockNote + @hocuspocus/provider + Supabase Realtime 做多人协作。
3) 文件上传 → Storage → POST /api/v1/tasks/ocr，订阅 background_tasks 进度；底部 AI 工具栏与面包屑就绪。
4) 后端实现 MinerU OCR 入队、LightRAG 增量索引，/api/v1/chat SSE 返回带引用的回答。
请输出完整代码修改列表，保持与 design3.0 数据流一致。

完成以上步骤，即视为 stage0 重构完成，可直接进入阶段 1 开发。

7.2 KiB Raw Permalink Blame History Unescape Escape