mnote/wolai-backend/README.md

wolai-backend（stage0 骨架）

本目录是 design3.0 指南下的 FastAPI + Celery 阶段 0 脚手架。当前目标：

1. 暴露健康检查与占位 API（/api/v1/tasks/ocr、/api/v1/chat），供前端联调。
2. 预留 Celery 队列、LightRAG、MinerU 集成点，但将重计算逻辑延后到阶段 1。
3. 依赖全部维护在 requirements.txt，其中 LightRAG 与 MinerU 通过本地源码安装，使用项目根目录已经下载好的仓库。

环境初始化

python -m venv venv
.\venv\Scripts\activate

# 如遇代理报错，可在同一终端先运行：
#   set HTTP_PROXY=
#   set HTTPS_PROXY=
#   set ALL_PROXY=
#   set NO_PROXY=*

# 安装 PyPI 依赖 + 本地 LightRAG （项目根目录已放置源码）
pip install -r requirements.txt

MinerU 已位于 services/mineru，按 README 启动为独立 OCR 服务，无需作为 Python 包安装。

运行服务

# FastAPI
uvicorn app.main:app --reload --port 8000

# Celery worker（后续阶段会真正处理 MinerU / LightRAG 作业）
celery -A app.workers.celery_app worker --loglevel=info

目录速览

app/
├── config.py           # Pydantic 设置，统一读取 .env
├── deps.py             # Supabase JWT / 客户端依赖
├── routers/
│   ├── health.py       # GET /health
│   ├── tasks.py        # POST /api/v1/tasks/ocr、GET /api/v1/tasks/{id}
│   └── chat.py         # GET /api/v1/chat（SSE 占位）
├── schemas/            # Pydantic 请求/响应模型
├── services/           # LightRAG、MinerU、Storage 等服务占位
└── workers/
    ├── celery_app.py   # Celery 配置
    └── tasks.py        # 后台任务入口（当前返回占位日志）

阶段 0 完成后，stage1 将在此基础上补充：

• MinerU OCR 实装（下载 Supabase Storage 文件 → 解析 → 更新 documents）
• LightRAG 的增量索引 / 查询
• SSE 流式回答 + 来源引用
• Redis/APScheduler 任务状态回传