🎉 Initial commit: QQuiz - 智能刷题与题库管理平台

## 功能特性

✅ **核心功能**
- 多文件上传与智能去重（基于 content_hash）
- 异步文档解析（支持 TXT/PDF/DOCX/XLSX）
- AI 智能题目提取与评分（OpenAI/Anthropic/Qwen）
- 断点续做与进度管理
- 自动错题本收集

✅ **技术栈**
- Backend: FastAPI + SQLAlchemy 2.0 + PostgreSQL
- Frontend: React 18 + Vite + Tailwind CSS
- Deployment: Docker Compose

✅ **项目结构**
- 53 个文件
- 完整的前后端分离架构
- Docker/源码双模部署支持

🚀 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -0,0 +1,152 @@
+# QQuiz - 智能刷题与题库管理平台
+
+QQuiz 是一个支持 Docker/源码双模部署的智能刷题平台，核心功能包括多文件上传、自动去重、异步解析、断点续做和错题本管理。
+
+## 功能特性
+
+- 📚 **多文件上传与去重**: 支持向同一题库追加文档，自动识别并过滤重复题目
+- 🤖 **AI 智能解析**: 支持 OpenAI/Anthropic/Qwen 多种 AI 提供商
+- 📊 **断点续做**: 自动记录刷题进度，随时继续
+- ❌ **错题本管理**: 自动收集错题，支持手动添加/移除
+- 🎯 **多题型支持**: 单选、多选、判断、简答
+- 🔐 **权限管理**: 管理员配置、用户隔离
+- 📱 **移动端优先**: 完美适配手机端
+
+## 快速开始
+
+### 方式一：Docker Compose (推荐)
+
+```bash
+# 1. 克隆项目
+git clone <repository-url>
+cd QQuiz
+
+# 2. 配置环境变量
+cp .env.example .env
+# 编辑 .env，填入你的 API Key 等配置
+
+# 3. 启动服务
+docker-compose up -d
+
+# 4. 访问应用
+# 前端: http://localhost:3000
+# 后端: http://localhost:8000
+# API 文档: http://localhost:8000/docs
+```
+
+### 方式二：本地运行
+
+#### 前置要求
+- Python 3.11+
+- Node.js 18+
+- PostgreSQL 15+
+
+```bash
+# 1. 配置环境变量
+cp .env.example .env
+# 编辑 .env，修改 DATABASE_URL 为本地数据库地址
+
+# 2. 启动 PostgreSQL
+# macOS: brew services start postgresql
+# Linux: sudo systemctl start postgresql
+
+# 3. 运行启动脚本
+chmod +x run_local.sh
+./run_local.sh
+```
+
+## 默认账户
+
+**管理员账户:**
+- 用户名: `admin`
+- 密码: `admin123`
+
+⚠️ **重要**: 首次登录后请立即修改密码！
+
+## 项目结构
+
+```
+QQuiz/
+├── backend/              # FastAPI 后端
+│   ├── alembic/          # 数据库迁移
+│   ├── routers/          # API 路由 (Step 2)
+│   ├── services/         # 业务逻辑 (Step 2)
+│   ├── models.py         # 数据模型 ✅
+│   ├── database.py       # 数据库配置 ✅
+│   ├── main.py           # 应用入口 ✅
+│   └── requirements.txt  # Python 依赖 ✅
+├── frontend/             # React 前端
+│   ├── src/
+│   │   ├── api/          # API 客户端 (Step 3)
+│   │   ├── pages/        # 页面组件 (Step 4)
+│   │   ├── components/   # 通用组件 (Step 4)
+│   │   └── App.jsx       # 应用入口 ✅
+│   ├── package.json      # Node 依赖 ✅
+│   └── vite.config.js    # Vite 配置 ✅
+├── docker-compose.yml    # Docker 编排 ✅
+├── .env.example          # 环境变量模板 ✅
+└── run_local.sh          # 本地运行脚本 ✅
+```
+
+## 核心业务流程
+
+### 1. 创建题库
+用户首次上传文档时，创建新的 Exam (题库容器)
+
+### 2. 追加文档
+在已有题库详情页点击 "添加题目文档"，上传新文件
+
+### 3. 去重逻辑
+- 对题目内容进行标准化处理 (去空格、标点、转小写)
+- 计算 MD5 Hash
+- 仅在当前题库范围内查询去重
+- 仅插入 Hash 不存在的题目
+
+### 4. 异步处理
+- 后台任务处理 AI 解析
+- 状态: `pending` → `processing` → `ready` / `failed`
+- 前端轮询状态，自动刷新
+
+### 5. 刷题体验
+- 基于 `current_index` 实现断点续做
+- 错题自动加入错题本
+- 简答题 AI 评分
+
+## 环境变量说明
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `DATABASE_URL` | 数据库连接字符串 | - |
+| `SECRET_KEY` | JWT 密钥 | - |
+| `AI_PROVIDER` | AI 提供商 (openai/anthropic/qwen) | openai |
+| `OPENAI_API_KEY` | OpenAI API 密钥 | - |
+| `ALLOW_REGISTRATION` | 是否允许注册 | true |
+| `MAX_UPLOAD_SIZE_MB` | 最大上传文件大小 (MB) | 10 |
+| `MAX_DAILY_UPLOADS` | 每日上传次数限制 | 20 |
+
+## 技术栈
+
+**后端:**
+- FastAPI - 现代化 Python Web 框架
+- SQLAlchemy - ORM
+- Alembic - 数据库迁移
+- PostgreSQL - 数据库
+- Pydantic - 数据验证
+
+**前端:**
+- React 18 - UI 框架
+- Vite - 构建工具
+- Tailwind CSS - 样式框架
+- React Router - 路由
+- Axios - HTTP 客户端
+
+## 开发进度
+
+- [x] **Step 1**: Foundation & Models ✅
+- [ ] **Step 2**: Backend Core Logic
+- [ ] **Step 3**: Frontend Config & API
+- [ ] **Step 4**: Frontend Complex UI
+
+## License
+
+MIT