# 智能复习平台后端 (Smart Review Backend)

基于 Spring Boot 3.2 的智能复习平台后端服务，集成阿里云百炼 AI 和 OSS 存储。

## 技术栈

- **框架**: Spring Boot 3.2.0
- **数据库**: MySQL 8.0 + Spring Data JPA
- **缓存**: Redis
- **AI服务**: 阿里云百炼 (DashScope)
- **存储**: 阿里云 OSS
- **认证**: JWT
- **文档解析**: flexmark-java (Markdown)
- **PDF导出**: iText7 + html2pdf

## 项目结构

```
src/main/java/com/smartreview/
├── SmartReviewApplication.java    # 主启动类
├── configure/                      # 配置类
│   ├── DashScopeConfig.java       # AI配置
│   ├── LoginInterceptor.java      # 登录拦截器
│   ├── RedisConfig.java           # Redis配置
│   ├── SecurityConfig.java        # 安全配置
│   └── WebMvcConfig.java          # Web配置
├── controller/                     # 控制器层
│   ├── UserController.java        # 用户认证
│   ├── DocumentController.java    # 文档管理
│   ├── BlockController.java       # 内容块
│   ├── CheckpointController.java  # 题目提交
│   ├── ReviewChatController.java  # AI对话
│   └── ReportController.java      # 复习报告
├── service/                        # 服务层
│   ├── impl/                      # 服务实现
│   └── AIService.java             # AI服务接口
├── repository/                     # 数据访问层
├── po/                            # 实体类
├── vo/                            # 值对象
├── enums/                         # 枚举类
├── exception/                     # 异常处理
└── utils/                         # 工具类
```

## API 接口

### 用户认证模块
| 接口                 | 方法 | 说明             |
| -------------------- | ---- | ---------------- |
| `/api/user/login`    | POST | 用户登录         |
| `/api/user/register` | POST | 用户注册         |
| `/api/user/info`     | GET  | 获取当前用户信息 |

### 文档管理模块
| 接口                   | 方法      | 说明                              |
| ---------------------- | --------- | --------------------------------- |
| `/api/document/upload` | POST      | 上传MD文档到OSS                   |
| `/api/document/parse`  | POST(SSE) | 解析文档 → 切分Block → 提取知识点 |
| `/api/document/list`   | GET       | 获取用户所有复习项目              |
| `/api/document/{id}`   | GET       | 获取文档详情 + 目录树             |
| `/api/document/{id}`   | DELETE    | 删除复习项目                      |

### 复习学习模块
| 接口                                     | 方法 | 说明                   |
| ---------------------------------------- | ---- | ---------------------- |
| `/api/block/{blockId}`                   | GET  | 获取Block原文内容      |
| `/api/block/{blockId}/progress`          | PUT  | 更新Block学习状态      |
| `/api/block/{blockId}/generate-question` | POST | 动态生成Checkpoint题目 |
| `/api/checkpoint/submit`                 | POST | 提交答案，返回批改结果 |

### AI助教模块（支持多轮对话）
| 接口                                | 方法      | 说明                       |
| ----------------------------------- | --------- | -------------------------- |
| `/api/chat/conversation`            | POST      | 创建新对话                 |
| `/api/chat/conversations`           | GET       | 获取对话列表               |
| `/api/chat/conversation/{id}`       | GET       | 获取对话详情（含消息历史） |
| `/api/chat/message`                 | POST(SSE) | 发送消息（流式响应）       |
| `/api/chat/conversation/{id}/close` | POST      | 关闭对话                   |
| `/api/chat/conversation/{id}`       | DELETE    | 删除对话                   |

### 复习报告模块
| 接口                           | 方法 | 说明             |
| ------------------------------ | ---- | ---------------- |
| `/api/report/{documentId}`     | GET  | 获取复习报告数据 |
| `/api/report/{documentId}/pdf` | GET  | 导出PDF报告      |

## 数据库表

1. **users** - 用户表
2. **documents** - 复习文档表
3. **chapters** - 章节表
4. **blocks** - 内容块表
5. **knowledge_points** - 知识点表
6. **questions** - 题目表
7. **user_answers** - 答题记录表
8. **conversations** - 对话会话表
9. **chat_messages** - 对话消息表

## 配置说明

编辑 `src/main/resources/application-dev.yml`:

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/smart_review
    username: your_username
    password: your_password

aliyun:
  oss:
    endpoint: oss-cn-hangzhou.aliyuncs.com
    accessKeyId: your_access_key_id
    accessKeySecret: your_access_key_secret
    bucketName: your_bucket_name

dashscope:
  api-key: your_dashscope_api_key
  model: qwen-plus  # 默认使用的模型
  models:
    knowledge-extractor: qwen-plus  # 知识点提取
    question-generator: qwen-plus   # 题目生成
    answer-grader: qwen-plus        # 问答题批改
    review-assistant: qwen-plus     # 复习助教对话
```

## 运行项目

1. 创建MySQL数据库：
```sql
CREATE DATABASE smart_review CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

2. 配置 `application-dev.yml` 中的数据库、OSS、DashScope信息

3. 启动Redis服务

4. 运行项目：
```bash
mvn spring-boot:run
```

## AI模型说明

本项目直接调用阿里云 DashScope 的大语言模型（如 qwen-plus），而不是调用智能体应用。

### 模型功能配置

在 `application-dev.yml` 中配置各功能使用的模型：

```yaml
dashscope:
  api-key: your_api_key
  model: qwen-plus  # 默认模型
  models:
    knowledge-extractor: qwen-plus  # 知识点提取
    question-generator: qwen-plus   # 题目生成
    answer-grader: qwen-plus        # 答案批改
    review-assistant: qwen-plus     # AI对话助教
```

### 1. 知识点提取 (knowledge-extractor)
**用途**: 从Block内容中提取3-5个关键知识点
**输出格式**: JSON数组
```json
[
  {"content": "知识点描述", "sourceText": "原文定位文字"}
]
```

### 2. 题目生成 (question-generator)
**用途**: 根据Block内容、知识点、用户提问历史动态生成题目
**输出格式**:
```json
{
  "type": "SINGLE/MULTIPLE/ESSAY",
  "questionText": "题目内容",
  "options": ["A. 选项1", ...],
  "correctAnswer": "正确答案",
  "explanation": "解析",
  "sourceEvidence": "原文依据"
}
```

### 3. 问答题批改 (answer-grader)
**用途**: 批改问答题答案
**输出格式**:
```json
{
  "score": 85,
  "feedback": "反馈意见",
  "reviewSuggestion": "回看建议"
}
```

### 4. 复习助教对话 (review-assistant)
**用途**: 支持自由对话和划词提问，帮助学生理解知识点
**特性**: 
- 支持多轮对话，保持上下文
- 支持流式响应
- 两种对话类型：FREE_CHAT（自由对话）、KNOWLEDGE_QA（知识点问答/划词提问）

## 多轮对话功能

### 对话类型
1. **FREE_CHAT（自由对话）**: 用户可以自由向AI助教提问
2. **KNOWLEDGE_QA（知识点问答）**: 用户划词选中文本后进行提问

### 对话流程
1. 创建对话 `POST /api/chat/conversation`
2. 发送消息 `POST /api/chat/message`（支持多轮）
3. 获取历史 `GET /api/chat/conversation/{id}`
4. 关闭/删除对话

## 核心功能

1. **文档解析**: 使用Markdown库解析MD文件，按标题层级切分章节，按段落切分Block
2. **知识点提取**: AI自动从每个Block中提取3-5个关键知识点
3. **动态题目生成**: 根据Block内容、知识点、用户提问历史智能生成checkpoint题目
4. **划词提问**: 用户选中文本后可向AI助教提问，提问内容会记录为知识点用于后续出题
5. **复习报告**: 生成包含进度、正确率、薄弱点、错题的复习报告，支持PDF导出