chore: init monorepo snapshot
This commit is contained in:
liaibo
@@ -0,0 +1,169 @@
|
||||
# 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 开发。
|
||||
Reference in New Issue
Block a user