# 考试管理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 调用失败时在控制台输出详细错误信息，并在界面上给出用户友好的提示
- 闯关模式中题目加载失败时显示重试按钮
- 错题本查询失败时降级显示空列表，不影响其他功能使用