# BE02 — 考试模块设计

> **版本：V1.1 | 参考：pj006-zhilianyuan2 exam/routes.py + exam/service.py**

---

## 1. 模块职责

- 题库管理（管理员 CRUD）
- 考试配置/组卷（管理员设置）
- 学员端考试（开始/答题/交卷/判分）
- 考试记录与回溯

## 2. 考试流程

```
管理员端：
  录入题目 → 配置考试（名称/类型/题量/总分/合格线/时长/随机）
  
员工端：
  考试列表 → 查看封面/说明 → 开始考试 → 答题 → 交卷
                  ↓                        ↓
           自测：即时显示对错+答案    正式考：存档（得分/明细/是否通过）
```

## 3. 数据表关系

```
question（题库）← exam_paper（考试配置，通过 domain+question_count 抽题）
                                                ↓
                                          exam_record（每次交卷的记录）
```

## 4. 题库 API

```python
# 管理员 — 题目 CRUD
GET    /api/exam/questions?domain=company&status=active    # 题目列表
POST   /api/exam/questions                                  # 新增题目
PUT    /api/exam/questions/{id}                             # 编辑题目
DELETE /api/exam/questions/{id}                             # 停用题目

# 管理员 — 考试配置
GET    /api/exam/papers                                     # 考试配置列表
POST   /api/exam/papers                                     # 创建考试
PUT    /api/exam/papers/{id}                                # 编辑考试
DELETE /api/exam/papers/{id}                                # 停用考试
```

## 5. 学员端考试 API

```python
GET    /api/exam/list                                       # 我的考试列表
GET    /api/exam/cover?id={paperId}                         # 考试封面/说明
POST   /api/exam/start                                      # 开始考试 → 下发题目
POST   /api/exam/submit                                     # 交卷判分
GET    /api/exam/record                                     # 我的考试记录
GET    /api/exam/record/{recordId}                          # 考试记录详情
```

## 6. 判分逻辑（参考 zhilianyuan2 _is_correct）

```python
# services/exam_service.py

def _is_correct(qtype: str, correct: list, user: any) -> bool:
    """确定性判分"""
    if qtype == "multiple":           # 多选题：集合相等
        return sorted(correct) == sorted(user) if user else False
    elif qtype == "judge":            # 判断题：值相等
        return str(correct).lower() == str(user).lower()
    else:                              # 单选题：值相等
        return correct == user

def grade_paper(questions: list, answers: dict) -> dict:
    """批卷：逐题比对 → 统计得分/正确数"""
    correct_count = 0
    total = len(questions)
    score_per_question = 100 / total if total else 0
    details = []
    
    for q in questions:
        user_ans = answers.get(str(q["id"]))
        is_correct = _is_correct(q["type"], q["answer"], user_ans)
        if is_correct:
            correct_count += 1
        details.append({
            "question_id": q["id"],
            "is_correct": is_correct,
            "user_answer": user_ans,
            "correct_answer": q["answer"],
        })
    
    score = round(score_per_question * correct_count)
    return {
        "score": score,
        "correct_count": correct_count,
        "wrong_count": total - correct_count,
        "passed": score >= paper.pass_score,
        "details": details,
    }
```

## 7. 自测 vs 正式考区别

| 维度 | 自测 (self_test) | 正式考 (formal) |
|------|-----------------|----------------|
| 次数限制 | 不限 | 按配置（通常 1 次） |
| 即时反馈 | 每题显示对错+答案 | 交卷后显示成绩 |
| 成绩存档 | 不存 | 永久保存到 exam_record |
| 答题明细 | 不存 | JSON 持久化 |

## 8. 考试记录设计

```json
// exam_record.detail_json 示例
{
  "questions": [
    {
      "question_id": 1,
      "stem": "博昇的主营业务包括？",
      "type": "single",
      "user_answer": "D",
      "correct_answer": "D",
      "is_correct": true,
      "explanation": "博昇双主营业务为资本咨询与AI产业落地"
    }
  ],
  "time_spent_sec": 1200
}
```

## 9. 权限

- **员工：** 仅查看自己的考试记录
- **管理员：** 查看全部考试记录（`/api/system/exam-records`）