# 学习助手 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 间隔重复算法实现个性化复习