前端项目初始化提交

docs/superpowers/specs/2026-05-10-exam-api-integration-design.md

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