# 试卷考核功能设计文档

> 日期: 2026-05-10
> 状态: 已批准
> 模块: 考察与训练 - 试卷考核子功能

## 一、功能概述

在现有「考察与训练」模块中新增 **试卷考核** 主标签页，为用户提供完整的考试流程：接收考试 → 答题 → 批改 → 查看成绩 → 错题练习。同时保留用户自行生成测试卷的能力。

## 二、模块架构

### 2.1 改造后的标签页结构

```
考察与训练 (exam)
├── 🤖 AI出题        (generate)   — exam:ai      — 管理员/有权限
├── 📚 题库管理      (bank)       — exam:bank    — 管理员/有权限
├── 📋 智能组卷      (paper)      — exam:paper   — 管理员专用（可编辑+发布）
├── 📝 试卷考核      (exam)       — exam:exam    — 全员（答题+错题+自测）
└── 🎯 互动训练      (train)      — exam:train   — 全员（闯关+每日一练）
```

### 2.2 试卷考核子标签页

```
试卷考核 [exam]
├── 📋 待考试      (pending)    — 管理员发布的待完成试卷列表
├── ✏️ 答题中      (taking)     — 全屏答题界面（当前正在答的试卷）
├── 📊 成绩单      (results)    — 已完成的试卷批改结果
├── ❌ 错题本      (wrong)      — 调用 wrong-questions/list API
└── 🔧 自测组卷    (selftest)   — 用户自行生成试卷（只生成不编辑，直接做题）
```

## 三、权限模型

### 3.1 新增权限代码

在 `permission.js` 的 `permissionCodeToModule` 中新增：

```javascript
'exam:exam': 'exam',           // 试卷考核 - 查看、答题、成绩、错题
'exam:exam:selftest': 'exam',  // 自测组卷 - 用户自行生成试卷
```

### 3.2 数据库新增权限记录

需在 `permission` 表中插入：

| permissionCode | permissionName | parentId(=exam节点ID) |
|---------------|---------------|---------------------|
| `exam:exam` | 试卷考核 | [exam父节点ID] |

### 3.3 角色分配建议

| 角色 | 可见标签页 |
|-----|----------|
| 超级管理员/管理员 | 全部5个（含智能组卷编辑发布） |
| 普通员工 | AI出题 + 试卷考核 + 互动训练 |

### 3.4 前端权限控制变量

```javascript
const canShowExam = computed(() =>
  hasChildPermission('exam:exam') || hasChildPermission('exam')
)
```

## 四、核心功能详细设计

### 4.1 待考试列表 (pending)

**功能**: 展示管理员通过「智能组卷」发布后、用户尚未完成的试卷。

**数据来源**: `GET /api/exam/my/papers` (§15.1)

**展示字段**:
- 试卷标题 (paper_title)
- 出卷人/来源
- 题目数量 (question_count)
- 总分 (total_score)
- 发布时间 (generated_at)
- 状态标签: `待考试`

**交互**: 点击卡片 → 进入全屏答题页面

**空状态**: "暂无待考试试卷，请等待管理员发布"

### 4.2 答题页面 (taking)

**功能**: 全屏沉浸式答题界面，支持5种题型的答案输入。

**触发**: 从待考试列表点击进入 / 从自测组卷生成后自动进入

**界面布局**:
```
┌─────────────────────────────────────────────┐
│ ⬅ 返回    📝 《试卷名称》         倒计时 ⏱️  │
├─────────────────────────────────────────────┤
│                                             │
│  第 1/13 题  [单选题]  ★ 5分                │
│  ───────────────────────────────────────    │
│  根据公司考勤制度，迟到15分钟以内的处罚是？   │
│                                             │
│  ○ A. 口头警告                               │
│  ○ B. 扣款50元                              │
│  ● C. 扣款100元                             │
│  ○ D. 视为旷工                              │
│                                             │
├─────────────────────────────────────────────┤
│              < 上一题    下一题 >   提交试卷  │
└─────────────────────────────────────────────┘
```

**题型渲染规则**:
| question_type | 控件 | 答案格式 |
|--------------|------|---------|
| single_choice | Radio 单选 | 字符串 "A" |
| multiple_choice | Checkbox 多选 | 数组 ["A","C"] |
| true_false | Radio 是/否 | 字符串 "true"/"false" |
| fill_blank | Input 输入框 | 字符串 |
| subjective | Textarea 文本域 | 字符串 |

**状态管理**:
```javascript
const currentTakingPaper = ref(null)       // 当前正在答的试卷
const currentQuestionIndex = ref(0)       // 当前题目索引
const takingAnswers = ref({})             // { questionId: answer }
const isSubmitting = ref(false)           // 提交中状态
```

**提交逻辑**:
1. 收集所有答案 → 构建 `answers` 数组
2. 调用 `POST /api/exam/grade` (§14.3)
3. 收到批改结果 → 自动跳转到成绩单视图
4. 错题自动标记 → 可在错题本中查看

### 4.3 成绩单 (results)

**功能**: 展示已完成的试卷批改结果。

**数据来源**: 提交批改时的响应 + `POST /api/exam/answers/query` (§14.4)

**展示内容**:
- 总分 / 得分 / 得分率
- 每道题的对错状态、得分、反馈
- 用时统计
- 操作按钮: 「查看解析」「重做错题」

### 4.4 错题本 (wrong)

**功能**: 展示用户的错题记录，支持查看解析和重做。

**数据来源**: `POST /api/wrong-questions/list` (§18.1)

**操作**:
- 查看解析: 显示标准答案 + AI反馈 + 选项高亮
- 重做: 调用 `POST /api/wrong-questions/redo` (§18.3) → 进入答题模式
- 收藏: 调用 `POST /api/wrong-questions/collection/toggle` (§18.2)

**与互动训练错题本的关系**:
- 互动训练的错题本是前端本地缓存（闯关/每日一练的错题）
- 试卷考核的错题本调用后端API，是持久化的真实错题数据
- 两者独立存在，互不影响

### 4.5 自测组卷 (selftest)

**功能**: 用户自行配置参数生成测试卷，生成后直接进入答题。

**API**: `POST /api/exam/paper/generate` (§14.1) — 用户版

**与智能组卷的区别**:

| 维度 | 智能组卷(管理员) | 自测组卷(用户) |
|-----|----------------|--------------|
| API | 同一个接口 | 同一个接口 |
| 生成后行为 | 进入编辑预览 | **直接进入答题** |
| 可编辑题目 | ✅ 编辑题干/选项/答案 | ❌ |
| 可发布给他人 | ✅ 发布按钮 | ❌ 仅自己使用 |
| 保存到试卷列表 | ✅ 存入后端 | ❌ 前端暂存 |
| 权限要求 | `exam:paper` | `exam:exam:selftest` |

**交互流程**:
1. 配置参数（题型数量、难度）→ 可选关联制度文件
2. 点击「开始测试」→ 调用 generatePaper API
3. 生成成功 → 自动切换到答题页面(taking)
4. 答题 → 提交批改 → 显示成绩

## 五、智能组卷改造（管理员增强）

### 5.1 新增能力

在现有的智能组卷功能上增加：

1. **编辑题目**: 在预览弹窗中点击题目旁的「编辑」按钮
   - 可修改: 题干(stem)、选项(options)、答案(answer)、分值(score)
   - 使用已有的 `showEditQuestionModal` 逻辑

2. **发布试卷**: 在预览弹窗底部增加「发布试卷」按钮
   - 调用后端发布接口（如需要新增接口则后续补充）
   - 发布成功后有 `exam:exam` 权限的用户可在「试卷考核-待考试」中看到

3. **试卷列表**: 增加本地已生成试卷的管理面板
   - 显示所有已生成的试卷（草稿/已发布）
   - 支持预览、编辑草稿、发布、删除

### 5.2 权限隔离

```javascript
// 只有拥有 exam:paper 权限的用户才能看到编辑和发布按钮
const canEditAndPublish = computed(() => hasChildPermission('exam:paper'))
```

## 六、API 接口清单

| 功能 | 方法 | 路径 | 文档章节 |
|-----|------|------|---------|
| 生成试卷(共用) | POST | `/api/exam/paper/generate` | §14.1 |
| 批改答案 | POST | `/api/exam/grade` | §14.3 |
| 查询答题记录 | POST | `/api/exam/answers/query` | §14.4 |
| 我的试卷列表 | GET | `/api/exam/my/papers` | §15.1 |
| 试卷详情 | GET | `/api/exam/paper/{paperId}` | §15.2 |
| 错题列表 | POST | `/api/wrong-questions/list` | §18.1 |
| 收藏错题 | POST | `/api/wrong-questions/collection/toggle` | §18.2 |
| 重做错题 | POST | `/api/wrong-questions/redo` | §18.3 |

## 七、文件变更清单

| 文件 | 变更类型 | 说明 |
|-----|---------|------|
| `src/utils/permission.js` | 修改 | 新增 `exam:exam` 权限映射 |
| `src/api/exam.js` | 已完成 | 所有API方法已在之前添加 |
| `src/components/ExamModule.vue` | 大幅修改 | 新增试卷考核标签页及全部子功能 |
| 数据库 permission 表 | 新增记录 | INSERT exam:exam 权限 |