QQuiz/README.md

QQuiz

QQuiz 是一个面向题库管理与刷题训练的全栈应用，支持文档导入、异步解析、题目去重、断点续做、错题本与管理员配置。

界面预览

核心能力

• 多文件导入与题目去重
• 异步解析进度回传
• 单选、多选、判断、简答题统一管理
• 刷题进度保存与继续作答
• 错题本与错题练习
• 管理员用户管理与系统配置
• 支持 Gemini / OpenAI / Anthropic / Qwen

当前架构

• backend/：FastAPI + SQLAlchemy + Alembic
• web/：当前主前端，Next.js App Router + TypeScript + Tailwind CSS
• frontend/：保留中的 legacy Vite 前端，用于单容器兼容路径

说明：

• 分离部署优先使用 web/
• 单容器镜像当前仍复用 frontend/ 构建静态资源

快速开始

1. 分离部署，推荐

前端运行在 3000，后端运行在 8000。

cp .env.example .env

docker compose up -d --build

访问地址：

• 前端：http://localhost:3000
• 后端：http://localhost:8000
• 后端健康检查：http://localhost:8000/health

2. 分离部署 + MySQL

cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.mysql.yml up -d --build

3. 单容器部署

单容器模式会把前端静态资源集成到后端服务中，统一通过 8000 提供。

cp .env.example .env

docker compose -f docker-compose-single.yml up -d --build

访问地址：

• 应用：http://localhost:8000
• API 文档：http://localhost:8000/docs

本地开发

后端

cd backend
pip install -r requirements.txt
alembic upgrade head
uvicorn main:app --reload --host 0.0.0.0 --port 8000

新前端

cd web
npm install
npm run dev

旧前端

仅在兼容或迁移场景下需要：

cd frontend
npm install
npm run dev

运行要求

• Python 3.11+
• Node.js 18+
• Docker / Docker Compose

关键环境变量

变量	说明
DATABASE_URL	数据库连接字符串
SECRET_KEY	JWT 密钥，至少 32 位
ADMIN_PASSWORD	默认管理员密码，至少 12 位
AI_PROVIDER	gemini / openai / anthropic / qwen
GEMINI_API_KEY	Gemini API Key
OPENAI_API_KEY	OpenAI API Key
OPENAI_BASE_URL	OpenAI 或兼容网关地址
ALLOW_REGISTRATION	是否允许注册
MAX_UPLOAD_SIZE_MB	单次上传大小限制
MAX_DAILY_UPLOADS	每日上传次数限制

更多示例见 .env.example。

目录结构

QQuiz/
├─ backend/                   FastAPI 后端
│  ├─ alembic/                数据库迁移
│  ├─ routers/                API 路由
│  ├─ services/               业务服务
│  ├─ models.py               ORM 模型
│  ├─ schemas.py              Pydantic Schema
│  └─ main.py                 应用入口
├─ web/                       Next.js 前端
│  ├─ src/app/                App Router 页面与 API Route
│  ├─ src/components/         UI 与业务组件
│  └─ src/lib/                前端 API、鉴权、工具
├─ frontend/                  Legacy Vite 前端
├─ docs/                      部署、审计与截图
├─ test_data/                 示例题库文件
├─ docker-compose.yml         前后端分离部署
├─ docker-compose.mysql.yml   MySQL overlay
├─ docker-compose-single.yml  单容器部署
└─ Dockerfile                 单容器镜像构建

技术栈

后端

• FastAPI
• SQLAlchemy 2.x
• Alembic
• SQLite / MySQL
• httpx
• OpenAI / Anthropic SDK

前端

• Next.js 14 App Router
• React 18
• TypeScript
• Tailwind CSS
• TanStack Query
• Radix UI / shadcn 风格组件

构建检查

常用检查命令：

cd web && npm run build
docker compose build backend frontend

仓库当前没有完整自动化测试套件，提交前至少建议手动验证：

• 登录 / 退出
• 创建题库 / 上传文档 / 查看解析进度
• 刷题与错题加入
• 管理员用户管理与系统设置
• 大数据量列表分页

开源协议

本项目采用 MIT License。