153 lines
5.1 KiB
Markdown
153 lines
5.1 KiB
Markdown
# 考试管理API对接设计文档
|
||
|
||
## 一、概述
|
||
|
||
### 1.1 目标
|
||
对「考察与训练」模块中的「智能组卷」和「互动训练」两个子功能进行后端API对接，替换现有的模拟数据，实现与后端考试管理接口的真实数据交互。
|
||
|
||
### 1.2 范围
|
||
- **智能组卷**: 使用 `POST /exam/paper/generate` 从题库自动组卷
|
||
- **互动训练-闯关模式**: 预设固定关卡，每关调用组卷接口生成题目
|
||
- **互动训练-错题本**: 使用 `POST /exam/answers/query` 查询答题记录
|
||
- **互动训练-每日一练**: 保持现有逻辑（已对接 `POST /exam/grade`）
|
||
|
||
### 1.3 约束
|
||
- 组卷结果仅前端暂存，不持久化到后端
|
||
- 闯关模式为预设固定关卡
|
||
- 仅修改前端，不修改后端代码
|
||
|
||
---
|
||
|
||
## 二、涉及接口
|
||
|
||
### 2.1 生成试卷 `POST /api/exam/paper/generate`
|
||
|
||
**请求参数**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| single_choice_count | Integer | 单选题数量 |
|
||
| multiple_choice_count | Integer | 多选题数量 |
|
||
| true_false_count | Integer | 判断题数量 |
|
||
| fill_blank_count | Integer | 填空题数量 |
|
||
| subjective_count | Integer | 简答题数量 |
|
||
| include_personal | Boolean | 是否包含个人题目 |
|
||
| difficulty | Integer | 难度等级(1-5) |
|
||
| file_ids | List<Long> | 关联文件ID列表 |
|
||
| collection | String | 向量库名称 |
|
||
| collection_name | String | 向量库名称（备选） |
|
||
|
||
**响应结构**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "试卷生成成功",
|
||
"data": {
|
||
"success": true,
|
||
"paper_id": "paper_xxx",
|
||
"paper_title": "试卷标题",
|
||
"total_score": 100,
|
||
"question_count": 10,
|
||
"generated_at": "2026-05-10T10:00:00",
|
||
"permission_scope": "department",
|
||
"warnings": {},
|
||
"questions": [
|
||
{
|
||
"question_id": "q-xxx",
|
||
"question_type": "single_choice",
|
||
"question_type_name": "单选题",
|
||
"difficulty": 2,
|
||
"score": 10,
|
||
"content": { "stem": "...", "data": { "options": [...] }, "answer": "A" }
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.2 批改答案 `POST /api/exam/grade`
|
||
已对接，无需修改。
|
||
|
||
### 2.3 查询答题记录 `POST /api/exam/answers/query`
|
||
|
||
**请求参数**:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| paper_id | String | 试卷ID（与session_id二选一） |
|
||
| session_id | String | 会话ID（与paper_id二选一） |
|
||
|
||
**响应结构**: 包含分组答题记录，其中 `is_correct` 为0时表示错误题目。
|
||
|
||
---
|
||
|
||
## 三、智能组卷改造
|
||
|
||
### 3.1 当前状态
|
||
`handleGeneratePaper()` 错误地调用了 `examAPI.generateQuestions()`（AI出题接口），而不是组卷专用接口。
|
||
|
||
### 3.2 改造内容
|
||
|
||
#### 3.2.1 新增 API 方法
|
||
在 [exam.js](file:///c:/Users/33520/Desktop/制度文件管理学习AI智能体 vue版本/src/api/exam.js) 中新增：
|
||
- `generatePaper(params)` → 调 `POST /api/exam/paper/generate`
|
||
|
||
#### 3.2.2 参数映射
|
||
| paperConfig | API字段 | 转换逻辑 |
|
||
|---|---|---|
|
||
| singleCount | single_choice_count | 直接映射 |
|
||
| multipleCount | multiple_choice_count | 直接映射 |
|
||
| judgmentCount | true_false_count | 直接映射 |
|
||
| essayCount | subjective_count | 直接映射 |
|
||
| difficulty (百分比) | difficulty | 加权计算: easy%×1 + medium%×3 + hard%×5 / 100 |
|
||
| doc | collection/collection_name/file_ids | 从FileSelector对象提取 |
|
||
|
||
#### 3.2.3 响应处理
|
||
API返回的 `data.questions` 包含完整的题目列表，直接作为试卷的题目内容保存在前端的 `papers` 数组中。
|
||
|
||
---
|
||
|
||
## 四、互动训练改造
|
||
|
||
### 4.1 闯关模式
|
||
|
||
#### 4.1.1 预设关卡设计
|
||
| 关卡 | 名称 | 题目数 | 难度 | 题型组成 |
|
||
|---|---|---|---|---|
|
||
| 1 | 入门挑战 | 5 | 1 | 3单选+2判断 |
|
||
| 2 | 基础巩固 | 8 | 2 | 4单选+2多选+2判断 |
|
||
| 3 | 进阶提升 | 10 | 3 | 4单选+3多选+3判断 |
|
||
| 4 | 高级挑战 | 10 | 4 | 3单选+3多选+2判断+2简答 |
|
||
| 5 | 大师试炼 | 12 | 5 | 4单选+4多选+2判断+2简答 |
|
||
|
||
每关调用 `POST /exam/paper/generate` 生成对应配置的题目。
|
||
|
||
#### 4.1.2 闯关流程
|
||
1. 用户点击关卡 → 调 `generatePaper()` 生成题目
|
||
2. 用户在弹窗中逐题作答
|
||
3. 点击提交 → 调 `examAPI.gradeAnswers()` 批改
|
||
4. 显示分数和结果 → 更新关卡状态
|
||
|
||
### 4.2 错题本
|
||
|
||
#### 4.2.1 数据来源
|
||
用户每次在闯关模式/每日一练中提交答案后：
|
||
1. 调用 `POST /exam/answers/query` 查询答题记录
|
||
2. 筛选 `is_correct === 0` 的题目作为错题
|
||
3. 按时间倒序排列展示
|
||
|
||
#### 4.2.2 本地缓存
|
||
每次批改后，将错题信息缓存到前端的 `wrongQuestions` 数组中，避免频繁调用查询接口。
|
||
|
||
---
|
||
|
||
## 五、文件修改清单
|
||
|
||
| 文件 | 修改内容 |
|
||
|------|---------|
|
||
| `src/api/exam.js` | 新增 `generatePaper()` 和 `queryUserAnswers()` 方法 |
|
||
| `src/components/ExamModule.vue` | 改造智能组卷和互动训练的数据流和API调用逻辑 |
|
||
|
||
## 六、错误处理
|
||
|
||
- API 调用失败时在控制台输出详细错误信息，并在界面上给出用户友好的提示
|
||
- 闯关模式中题目加载失败时显示重试按钮
|
||
- 错题本查询失败时降级显示空列表，不影响其他功能使用 |