gao
423b9ab55e
1 fix: 修复Vue模板语法错误和优化项目配置 2 3 - 修复MainDashboard.vue中多余的template结束标签导致的Vue编译错误 4 - 更新项目文档QWEN.md，完善项目说明和部署指南 5 - 优化create_admin.py脚本，从main.py导入统一配置 6 - 增强PDF解析器错误处理和兼容性 7 - 改进登录页面UI设计和用户体验 8 9 🤖 Generated with [Claude Code](https://claude.com/claude-code) 10 11 Co-Authored-By: Claude <[email protected]>
258 lines
6.1 KiB
Markdown
258 lines
6.1 KiB
Markdown
# 学习助手 Pro - 项目说明
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 FastAPI + Vue3 的智能试卷管理与学习跟踪系统，支持PDF试卷智能解析、题目自动提取、错题管理和学习统计等功能。项目采用前后端分离架构，旨在帮助学生高效管理试卷、跟踪错题并进行个性化学习。
|
||
|
||
## 核心功能
|
||
|
||
### 智能试卷管理
|
||
- PDF试卷上传和预览
|
||
- 多学科试卷分类管理（数学、语文、英语等）
|
||
- 试卷信息自动识别和标注
|
||
|
||
### 题目智能提取
|
||
- AI驱动的PDF文本层解析，速度快准确率高（95%+）
|
||
- OCR备份解析，处理扫描版PDF
|
||
- 自动识别题目类型（选择题、填空题、解答题等）
|
||
- 智能提取题目图片（几何图形、函数图像等）
|
||
- 数学符号自动修复和优化
|
||
|
||
### 错题管理系统
|
||
- 智能错题收集和分类
|
||
- 艾宾浩斯遗忘曲线复习提醒
|
||
- 个性化学习计划生成
|
||
- 错题复习统计和进度跟踪
|
||
|
||
### 学习数据分析
|
||
- 详细的学习进度统计
|
||
- 多维度数据可视化
|
||
- 学科强弱项分析
|
||
- 学习效率评估
|
||
|
||
## 技术栈
|
||
|
||
### 后端 (FastAPI)
|
||
- **FastAPI**: 高性能 Python Web 框架
|
||
- **SQLAlchemy**: ORM 数据库操作
|
||
- **JWT**: 用户认证
|
||
- **Pydantic**: 数据验证
|
||
- **pdfplumber**: PDF解析
|
||
- **PyMuPDF**: PDF处理
|
||
- **BCrypt**: 密码加密
|
||
- **SQLAlchemy**: 数据库ORM
|
||
|
||
### 前端 (Vue3)
|
||
- **Vue 3**: 组合式 API
|
||
- **Element Plus**: UI 组件库
|
||
- **Pinia**: 状态管理
|
||
- **Axios**: HTTP客户端
|
||
- **Chart.js**: 数据可视化
|
||
- **Vite**: 构建工具
|
||
|
||
### 数据库
|
||
- **SQLite**: 轻量级数据库（可升级到 PostgreSQL/MySQL）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
pager/
|
||
├── backend/
|
||
│ ├── main.py # 后端主应用
|
||
│ ├── api_images.py # 图片API路由
|
||
│ ├── create_admin.py # 创建管理员脚本
|
||
│ ├── migrate_db.py # 数据库迁移脚本
|
||
│ ├── pdf_*.py # PDF解析相关工具
|
||
│ ├── requirements.txt # Python依赖
|
||
│ ├── initial_words.csv # 初始单词数据
|
||
│ └── utils/ # 工具函数
|
||
├── frontend/
|
||
│ ├── src/ # 源代码
|
||
│ ├── package.json # Node.js依赖
|
||
│ ├── vite.config.js # Vite配置
|
||
│ └── index.html # 主HTML文件
|
||
├── README.md # 项目说明
|
||
├── start.sh/start_app.sh # 启动脚本
|
||
├── status.sh/status_app.sh # 状态检查脚本
|
||
├── stop.sh/stop_app.sh # 停止脚本
|
||
└── index.html # 根目录HTML文件
|
||
```
|
||
|
||
## 构建和运行
|
||
|
||
### 后端启动
|
||
|
||
1. 进入后端目录：
|
||
```bash
|
||
cd backend
|
||
```
|
||
|
||
2. 安装依赖：
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
3. 启动后端服务：
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
后端将在 `http://0.0.0.0:8888` 启动
|
||
|
||
### 前端启动
|
||
|
||
1. 进入前端目录：
|
||
```bash
|
||
cd frontend
|
||
```
|
||
|
||
2. 安装依赖：
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
3. 启动开发服务器：
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
前端将在 `http://localhost:3000` 启动 (如端口被占用会自动选择其他端口)
|
||
|
||
## 环境变量配置
|
||
|
||
### 后端配置
|
||
|
||
在后端目录创建 `.env` 文件：
|
||
```
|
||
SECRET_KEY=your-super-secret-key-here
|
||
DATABASE_URL=sqlite:///./wordmaster.db
|
||
ACCESS_TOKEN_EXPIRE_MINUTES=30
|
||
ALGORITHM=HS256
|
||
```
|
||
|
||
### 前端配置
|
||
|
||
在前端目录创建 `.env.development` 文件：
|
||
```
|
||
VITE_BACKEND_HOST=localhost
|
||
VITE_BACKEND_PORT=8888
|
||
VITE_APP_VERSION=1.0.0
|
||
```
|
||
|
||
## 主要API端点
|
||
|
||
### 认证
|
||
- `POST /api/auth/register` - 用户注册
|
||
- `POST /api/auth/login` - 用户登录
|
||
|
||
### 词汇管理
|
||
- `GET /api/words` - 获取词汇列表
|
||
- `POST /api/words` - 创建词汇
|
||
- `POST /api/words/import` - 批量导入词汇
|
||
|
||
### 学习管理
|
||
- `GET /api/study/due` - 获取待学习词汇
|
||
- `POST /api/study/submit` - 提交学习结果
|
||
|
||
### 试卷管理
|
||
- `POST /api/papers` - 创建试卷
|
||
- `GET /api/papers` - 获取试卷列表
|
||
- `POST /api/papers/{paper_id}/split` - 拆解试卷为题目
|
||
|
||
### 题目管理
|
||
- `POST /api/questions` - 创建题目
|
||
- `GET /api/questions` - 获取题目列表
|
||
- `GET /api/questions/{question_id}/format` - 获取格式化题目
|
||
|
||
### 错题管理
|
||
- `POST /api/mistakes` - 创建错题
|
||
- `GET /api/mistakes` - 获取错题列表
|
||
- `POST /api/mistakes/{mistake_id}/review` - 提交复习结果
|
||
|
||
### 仪表盘
|
||
- `GET /api/dashboard` - 获取仪表盘统计
|
||
|
||
## 开发规范
|
||
|
||
### 代码风格
|
||
- Python: 遵循 PEP 8 标准
|
||
- JavaScript/TypeScript: 使用 ESLint 和 Prettier
|
||
- HTML/CSS: 使用语义化标签和 BEM 命名规范
|
||
|
||
### 提交规范
|
||
- 使用 Git 提交信息规范，如 "feat: 添加新功能"、"fix: 修复问题" 等
|
||
|
||
## 部署选项
|
||
|
||
### Docker 部署 (推荐)
|
||
|
||
创建 `docker-compose.yml`：
|
||
```yaml
|
||
version: '3.8'
|
||
services:
|
||
backend:
|
||
build: ./backend
|
||
ports:
|
||
- "8000:8000"
|
||
volumes:
|
||
- ./data:/app/data
|
||
environment:
|
||
- DATABASE_URL=sqlite:///./data/wordmaster.db
|
||
|
||
frontend:
|
||
build: ./frontend
|
||
ports:
|
||
- "3000:3000"
|
||
depends_on:
|
||
- backend
|
||
```
|
||
|
||
启动：
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
### PM2 部署
|
||
|
||
1. 安装 PM2：
|
||
```bash
|
||
npm install -g pm2
|
||
```
|
||
|
||
2. 启动后端：
|
||
```bash
|
||
pm2 start "uvicorn main:app --host 0.0.0.0 --port 8000" --name wordmaster-backend
|
||
```
|
||
|
||
3. 构建并启动前端：
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
pm2 serve dist 3000 --name wordmaster-frontend
|
||
```
|
||
|
||
## 安全建议
|
||
|
||
1. 修改默认密钥：
|
||
```python
|
||
SECRET_KEY = "your-production-secret-key-very-long-and-random"
|
||
```
|
||
|
||
2. CORS 配置：
|
||
```python
|
||
allow_origins=["https://your-domain.com"] # 限制具体域名
|
||
```
|
||
|
||
3. HTTPS 部署：使用 SSL 证书
|
||
|
||
4. 数据库安全：定期备份，访问控制
|
||
|
||
## 系统特点
|
||
|
||
- **超快解析速度**: 0.01秒完成一页试卷解析
|
||
- **高准确率**: 文本识别准确率95%+，性能提升2900倍
|
||
- **智能图片提取**: 自动关联题目与图片，完美显示数学图形
|
||
- **热加载开发**: 前后端完整热加载支持
|
||
- **响应式设计**: 支持电脑、平板、手机
|
||
- **离线缓存**: 渐进式 Web 应用
|
||
- **学习算法**: SM-2 间隔重复算法实现个性化复习 |