chore: init monorepo snapshot

2025-11-23 10:55:04 +08:00
commit c70ff52869
941 changed files with 246586 additions and 0 deletions
@@ -0,0 +1,304 @@
+以下是**完全适配 design3.0.md（前后端分离 + MinerU + LightRAG 版）的全新阶段 0 重做指南**。  
+目标：在 1～2 天（AI 助手 < 4 小时）内把你已经跑完旧 stage0 的项目**安全迁移/拆分**成两个干净仓库：
+
+```
+wolai-frontend   ← 只负责 UI + 实时协作 + 轻量调用后端 API
+wolai-backend    ← FastAPI + Celery Redis LightRAG MinerU 全包
+```
+
+最终状态：  
+- 前端仍然是 Next.js 15 App Router + Supabase Auth/Realtime/Storage  
+- 所有重量级任务（OCR、向量化、知识图谱构建、RAG 查询）全部后端完成  
+- 0 客户端卡顿  
+- 两边共享同一 Supabase 项目（Auth + Postgres + Storage + Realtime）  
+- 代码结构、环境变量、数据库表 100% 符合 design3.0.md 最新要求  
+
+---  
+
+### 第一步：备份 & 拆分仓库（必须先做，防止误删）
+
+```bash
+# 在你当前项目根目录
+mv wolai-clone wolai-clone-old-backup-$(date +%Y%m%d)
+
+# 新建两个干净文件夹
+mkdir wolai-frontend wolai-backend
+```
+
+### 第二步：创建全新前端项目（保留必要依赖，卸载已迁移到后端的包
+
+```bash
+# 进入前端目录
+cd wolai-frontend
+
+npx create-next-app@latest . \
+  --typescript \
+  --tailwind \
+  --eslint \
+  --app \
+  --src-dir \
+  --import-alias "@/*" \
+  --turbo \
+  --yes
+
+# 初始化 shadcn（2025-11 最新版默认 darkMode: "class"）
+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
+
+# 一次性加常用 shadcn 组件（和以前一样）
+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
+```
+
+**需要卸载的旧依赖（因为已移到后端）**
+```bash
+pnpm remove \
+  @blocknote/mantine \
+  tesseract.js \
+  pdfjs-dist \
+  langchain \
+  @langchain/openai \
+  @langchain/community \
+  neo4j-driver \
+  @neo4j/graphql
+```
+
+### 第三步：前端目录结构（AI 接手零摩擦）
+
+```
+src/
+├── app/
+│   ├── (auth)/          # 登录注册页
+│   ├── (app)/           # 主体布局
+│   │   ├── documents/
+│   │   │   ├── [id]/
+│   │   │   │   ├── page.tsx         # BlockNote + XYFlow 切换
+│   │   │   │   └── mindmap/page.tsx
+│   │   └── layout.tsx       # Sidebar + Breadcrumb + BottomToolbar
+│   ├── api/                 # 只保留轻量 route handlers（如上传文件到 Storage）
+│   ├── globals.css
+│   └── layout.tsx
+├── components/
+│   ├── editor/     # BlockNoteEditor.tsx + 实时协作
+│   ├── mindmap/    # ReactFlow 组件
+│   ├── sidebar/
+│   ├── ui/         # shadcn
+│   └── common/
+├── lib/
+│   └── supabase/   # client.ts + server.ts（保持不变）
+├── hooks/
+└── store/          # zustand
+```
+
+### 第四步：创建后端 FastAPI 项目（全新仓库）
+
+```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 \
+  python-jose[cryptography] \
+  passlib[bcrypt]
+
+# 创建基本结构
+mkdir app
+touch app/main.py app/celery_app.py app/tasks.py app/lightrag_utils.py app/__init__.py
+```
+
+**推荐的初始文件（直接复制即可）**
+
+```python
+# app/main.py
+from fastapi import FastAPI, Depends, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from supabase import create_client
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = FastAPI(title="Wolai Backend v3.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000", os.getenv("FRONTEND_URL")],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+supabase = create_client(os.getenv("SUPABASE_URL"), os.getenv("SUPABASE_SERVICE_ROLE_KEY"))
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+```
+
+```python
+# app/celery_app.py
+from celery import Celery
+
+celery = Celery(
+    "worker",
+    broker=os.getenv("REDIS_URL"),
+    backend=os.getenv("REDIS_URL")
+)
+celery.conf.task_default_queue = "wolai"
+celery.conf.worker_concurrency = 3
+```
+
+### 第五步：Supabase 数据库表（2025-11-17 最新版）直接在 SQL Editor 全部执行
+
+```sql
+-- 1. 启用扩展
+create extension if not exists "uuid-ossp";
+create extension if not exists vector;
+
+-- 2. 文档表（新增字段）
+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,                         -- MinerU 提取的纯文本
+  index_status text default 'pending',    -- pending / processing / completed / failed
+  created_at timestamptz default now(),
+  updated_at timestamptz default now()
+);
+
+-- 3. 后台任务进度表（前端轮询或 Realtime 订阅）
+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()
+);
+
+-- 4. RLS
+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 会自动在你的 Supabase 里创建自己的表（embeddings、entities、relationships 等），不需要手动建。
+
+### 第六步：环境变量（两个项目都要）
+
+**前端 .env.local**
+```env
+NEXT_PUBLIC_SUPABASE_URL=https://xxxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+NEXT_PUBLIC_BACKEND_URL=http://localhost:8000      # 开发时
+# 生产时改成你的 Railway/Fly.io 域名
+```
+
+**后端 .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=https://your-frontend.vercel.app
+```
+
+### 第七步：Git 初始化（推荐两个仓库）
+
+```bash
+# 前端
+cd wolai-frontend
+git init
+git add .
+git commit -m "chore: phase0 frontend - nextjs15 + supabase + blocknote + xyflow (2025-11-17 v3)"
+git tag -a "v0.1.0-phase0-frontend" -m "design v3.0 ready"
+
+# 后端
+cd ../wolai-backend
+git init
+git add .
+git commit -m "chore: phase0 backend - fastapi + celery + lightrag + mineru (2025-11-17 v3)"
+git tag -a "v0.1.0-phase0-backend" -m "design v3.0 ready"
+```
+
+### 第八步：交给 AI 编码助手的“一键 Prompt”（直接复制丢给 Claude/Cursor/Codex）
+
+```text
+你现在是一个顶级全栈工程师，需要严格按照 design3.0.md（2025-11-17 最新版）实现 Wolai 克隆，要求前后端完全分离。
+
+仓库状态：
+- wolai-frontend：Next.js 15 App Router + TypeScript + Tailwind + shadcn/ui + Supabase 客户端已就绪，依赖已精简
+- wolai-backend：FastAPI + Celery + Redis + LightRAG + MinerU 骨架已就绪，Supabase service_role 已配置
+
+请完成以下阶段 1 任务（只做前端 + 后端必要接口）：
+
+前端：
+1. 实现递归侧边栏（240px，@hello-pangea/dnd 拖拽，无限嵌套，参考 ui_react.md 像素级复刻）
+2. /documents/[id]/page.tsx 使用 BlockNote + @hocuspocus/provider + Supabase Realtime 实现多人实时协作
+3. 实现面包屑、底部固定 AI 工具栏、移动端 Drawer 侧边栏
+4. 文件上传 → Supabase Storage → 调用后端 POST /api/v1/tasks/ocr {document_id, file_url} → 显示 background_tasks 进度（Realtime 订阅）
+
+后端：
+1. /api/v1/tasks/ocr 接口（接收 document_id + signed_url，使用 service_role 下载文件 → Celery 任务执行 MinerU → 保存 markdown 到 documents.content + raw_text → LightRAG.index）
+2. /api/v1/chat SSE 流式接口（LightRAG.query + OpenAI gpt-4o，带来源引用）
+
+全部使用 Server Components + Server Actions（前端） 和 FastAPI Depends 验证 Supabase JWT（后端）。
+代码必须 100% 符合 design3.0.md 表结构与数据流。
+请输出完整文件列表与代码。
+```
+
+执行完以上所有步骤后，你就拥有了一个**完全符合 2025-11-17 最新 design3.0.md 的干净双仓库**，可以直接丢给 AI 继续阶段 1。
+
+现在只需要运行：
+
+```bash
+# 前端
+cd wolai-frontend && pnpm dev
+
+# 后端
+cd wolai-backend
+uvicorn app.main:app --reload --port 8000
+celery -A app.celery_app worker --loglevel=info
+```
+
+两个项目同时启动，就能看到熟悉的 Wolai 界面，上传 PDF 后进度条实时显示，AI 问答秒回。
+
+到此，阶段 0（v3.0 版）完成。接下来直接把第八步的 Prompt 丢给 Claude/Cursor 即可进入高速开发阶段。  
+
+祝编码愉快！