# 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. 先备份再拆分
```bash
mv wolai-clone wolai-clone-old-backup-$(date +%Y%m%d)
mkdir wolai-frontend wolai-backend
```
> 备份后再动代码，避免误删。

## 2. 前端脚手架（UI + 实时协作）
```bash
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. 后端脚手架（重计算全搬来）
```bash
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 执行）
```sql
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`
```env
NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
```

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

## 7. Git 记录（拆分后各自初始化）
```bash
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 开发。