aurak/docs/plans/2026-04-23-assessment-system-full-plan.md

# AuraK 人才测评体系完整实施计划

> **文档状态**: 待评审
> **创建日期**: 2026-04-23
> **版本**: 1.0

---

## 一、系统概述

### 1.1 目标

构建一个完整的AI人才测评体系，实现"选→育→评→用"闭环。聚焦在**评（认证）阶段**，形成包含题库管理、评估执行、成绩管理、证书管理的完整系统。

### 1.2 核心流程

```
人才输入 → 评估执行 → 结果输出 → 应用决策
              ↑___________↓
               持续反馈
```

### 1.3 评估发起模式

| 场景 | 发起方式 |
|------|---------|
| 新人入职认证 | 管理员发起（强制） |
| 认证后自评 | 学员可自评 |

---

## 二、组织架构与权限设计

### 2.1 组织结构

```
公司
 ├── 本部A
 │    ├── 开发部
 │    └── 其他部门
 └── 本部B
      ├── 开发部
      └── 其他部门
```

### 2.2 角色权限矩阵

| 角色 | 查看自己 | 查看本部门 | 查看全公司 | 题库管理 | 发起评估 | 复查 |
|------|---------|-----------|-----------|---------|---------|------|
| 学员 | ✅ | ❌ | ❌ | ❌ | 自评 | ❌ |
| 开发部长 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 本部长 | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 公司高管 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| 管理员 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 讲师 | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |

### 2.3 权限规则

- 学员只能看自己的历史成绩
- 各级管理者可查看下属员工成绩
- 管理员可查看全部数据、管理题库
- 讲师仅用于复查调整分数

---

## 三、模块A：题库管理

### 3.1 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 创建题库 | 关联知识库，设定题目范围 | P0 |
| 单题管理 | 增删改查，支持简答/选择/判断 | P0 |
| AI批量生成 | 按模板维度配置生成待审题目 | P0 |
| 智能标注 | AI自动标注维度、难度 | P1 |
| 审核流程 | 草稿→待审→发布/否决 | P0 |
| 相似检测 | 检测与已有题目重复度 | P2 |
| 查询统计 | 多条件筛选、维度分布、使用统计 | P1 |

### 3.2 题目属性

| 属性 | 类型 | 说明 |
|------|------|------|
| questionText | string | 题干文字 |
| questionType | enum | SHORT_ANSWER/MULTIPLE_CHOICE/TRUE_FALSE |
| options | string[] | ABCD选项 |
| correctAnswer | string | 正确答案 |
| keyPoints | string[] | 评分要点 |
| difficulty | enum | STANDARD/ADVANCED/SPECIALIST |
| dimension | enum | PROMPT/LLM/IDE/DEV_PATTERN/WORK_CAPABILITY |
| basis | string | 出题依据 |

### 3.3 题目与知识库关联

- **方案**：题目不单独关联知识库
- 由模板指定知识库范围，范围内题目均可被抽取
- 模板预设各维度的题目数量

### 3.4 审核流程

```
草稿(DRAFT)
    ↓ [提交审核]
待审核(PENDING_REVIEW)
    ↓ [通过]     ↓ [否决]
已发布(PUBLISHED)  草稿(DRAFT)
                    + 审核意见
```

### 3.5 版本管理

- 简化版：仅记录最近一次修改时间和修改人

### 3.6 数据模型

```typescript
// QuestionBank 实体
{
  id: string;
  templateId: string;           // 关联模板
  name: string;                 // 题库名称
  description: string;          // 描述
  status: enum;                // DRAFT/PENDING_REVIEW/PUBLISHED
  createdBy: string;
  reviewedBy: string;          // 审核人
  reviewedAt: Date;             // 审核时间
  reviewComment: string;       // 审核意见
  createdAt: Date;
  updatedAt: Date;
}

// QuestionBankItem 实体
{
  id: string;
  bankId: string;              // 关联题库
  questionText: string;        // 题干
  questionType: enum;           // 题型
  options: string[];           // 选项
  correctAnswer: string;        // 答案
  keyPoints: string[];          // 关键点
  difficulty: enum;            // 难度
  dimension: enum;             // 维度
  basis: string;               // 出题依据
  createdBy: string;
  createdAt: Date;
}
```

### 3.7 API设计

```typescript
// 题库CRUD
POST   /api/question-banks              // 创建题库
GET    /api/question-banks              // 列表（分页）
GET    /api/question-banks/:id          // 详情
PUT    /api/question-banks/:id          // 更新
DELETE /api/question-banks/:id          // 删除

// 题目管理
POST   /api/question-banks/:bankId/items      // 添加题目
PUT    /api/question-banks/:bankId/items/:id  // 更新题目
DELETE /api/question-banks/:bankId/items/:id  // 删除题目

// 批量操作
POST   /api/question-banks/:bankId/generate   // AI批量生成
POST   /api/question-banks/:bankId/batch-add   // 批量导入

// 审核流程
PUT    /api/question-banks/:id/submit    // 提交审核
PUT    /api/question-banks/:id/review     // 审核
PUT    /api/question-banks/:id/publish    // 发布
PUT    /api/question-banks/:id/unpublish  // 下架

// 查询
GET    /api/question-banks/by-template/:templateId  // 按模板查询
```

---

## 四、模块B：评估执行

### 4.1 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 题目抽取 | 按模板/维度均衡/高频优先抽取 | P0 |
| 答题交互 | 展示题目、接收答案、即时反馈 | P0 |
| AI评分 | 按关键点评分，0-10分 | P0 |
| 追问机制 | 预置追问+超时降级 | P0 |
| 时间控制 | 单题限时+总时长限制 | P1 |
| 成绩判定 | ≥6分通过 | P0 |

### 4.2 题目抽取算法

```typescript
function selectQuestions(bankId, templateConfig) {
  // 1. 按模板指定的知识库范围查已发布题目
  // 2. 按维度比例随机抽取
  // 3. 高频题目优先被抽（不限制重复次数）
  // 4. 不足时提示"题库不足"
}
```

### 4.3 追问机制

| 方案 | 说明 |
|------|------|
| 预置追问 | 题库中预存追问内容 |
| 实时补充 | 超时则降级跳过 |
| 追问限制 | 最多2次追问 |

### 4.4 时间控制

| 限制 | 说明 | 默认值 |
|------|------|--------|
| 单题限时 | 超时强制下一题 | 300秒 |
| 总时长限制 | 超时强制提交 | 1800秒 |

### 4.5 评估流程

```
开始评估
    ↓
加载模板（数量/维度/时长）
    ↓
从题库抽取题目（维度均衡）
    ↓
展示第1题
    ↓
用户答题
    ↓
AI评分（按关键点0-10分）
    ↓
追问?（预置+超时降级）
    ↓
下一题（循环至最后一题）
    ↓
生成报告 + 判断通过/未通过（≥6分）
    ↓
通过 → 发放证书
```

### 4.6 API设计

```typescript
// 评估管理
POST   /api/assessment/start              // 发起评估
GET    /api/assessment/:id/state          // 获取状态
POST   /api/assessment/:id/answer         // 提交答案

// 评估管理（管理员）
GET    /api/assessment                    // 所有评估列表
GET    /api/assessment/:id                // 评估详情
DELETE /api/assessment/:id               // 删除评估
```

---

## 五、模块C：成绩管理

### 5.1 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 成绩查看 | 按权限查看成绩 | P0 |
| 统计报表 | 通过率/分数/趋势/雷达图 | P1 |
| 历史管理 | 保留最近3次 | P1 |
| 导出功能 | Excel/PDF/CSV | P1 |
| 复查功能 | 讲师调整分数 | P2 |

### 5.2 统计维度

| 维度 | 说明 |
|------|------|
| 通过人数/通过率 | 整体和分组 |
| 平均分/最高分/最低分 | 按组统计 |
| 各维度平均分 | 雷达图数据 |
| 评估次数趋势 | 时序折线图 |

### 5.3 报表页面

```
┌──────────────────────────────────────────┐
│ 成绩统计                    [导出] [筛选] │
├──────────────────────────────────────────┤
│  总人数  │  通过率  │  平均分  │  待审核  │
│   156    │   82%    │   7.5    │    3     │
├──────────────────────────────────────────┤
│  雷达图（各维度平均分）                   │
│         prompt ████████ 8.2            │
│           llm ███████░░ 7.6            │
│           ide ██████░░░ 6.8            │
│   devPattern █████░░░░ 6.2            │
│  workCap ██████░░░░ 6.5            │
├──────────────────────────────────────────┤
│  成绩列表（按组织筛选）                   │
│  姓名  │ 部门  │ 分数 │ 状态 │ 时间 │ 操作 │
│  [查看] │ [复查]                             │
└────────────────���─────────────────────────┘
```

### 5.4 API设计

```typescript
// 成绩统计
GET    /api/assessment/stats                    // 当前用户统计
GET    /api/assessment/stats/admin             // 管理员统计
Query: startDate, endDate, templateId, groupId

// 复查
PUT    /api/assessment/:id/review              // 调整分数
```

---

## 六、模块D：证书管理

### 6.1 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 证书生成 | 通过即发 | P1 |
| 证书下载 | PDF导出 | P1 |
| 证书验真 | 二维码/ID查询 | P1 |

### 6.2 证书内容

| 字段 | 说明 |
|------|------|
| certificateId | 唯一ID |
| userId | 持证人 |
| templateId | 评估模板 |
| totalScore | 总分 |
| passedAt | 通过时间 |
| qrCode | 防伪二维码 |

### 6.3 有效期

- **永久有效**：一次通过，终身有效

### 6.4 证书样式

```
┌────────────────────────────────────────┐
│          [公司LOGO]                    │
│                                     │
│         能力认证证书                 │
│                                     │
│   兹证明 [学员姓名] 通过              │
│   [评估模板名称] 能力评估             │
│   总分：[分数] 分                    │
│                                     │
│   发证日期：[日期]                   │
│   证书编号：[ID]                     │
│                                     │
│         [二维码]                      │
│         验证真伪                      │
└────────────────────────────────────────┘
```

### 6.5 API设计

```typescript
// 证书
GET    /api/assessment/:id/certificate         // 获取证书
GET    /api/assessment/:id/certificate/download // 下载PDF
POST   /api/assessment/certificate/verify     // 验证证书
```

---

## 七、实施计划

### 7.1 任务分解

| Phase | Task | 内容 | 优先级 |
|-------|------|------|--------|
| 1 | A1 | 题库实体创建 | P0 |
| 1 | A2 | 题目实体创建 | P0 |
| 1 | A3 | 题库Service/Controller | P0 |
| 1 | A4 | AI批量生成 | P0 |
| 1 | A5 | 审核流程 | P0 |
| 2 | B1 | 题目抽取算法 | P0 |
| 2 | B2 | 评估流程接入题库 | P0 |
| 2 | B3 | 追问预置+降级 | P0 |
| 2 | B4 | 时间控制 | P1 |
| 3 | C1 | 统计API | P1 |
| 3 | C2 | 报表前端 | P1 |
| 3 | C3 | 历史管理 | P1 |
| 3 | C4 | 导出功能 | P1 |
| 4 | D1 | 证书实体 | P1 |
| 4 | D2 | 证书生成 | P1 |
| 4 | D3 | 证书下载/验真 | P1 |
| 5 | E1 | 复查功能 | P2 |

### 7.2 执行顺序

```
Phase 1 (题库)
    ↓
Phase 2 (评估)
    ↓
Phase 3 (成绩)
    ↓
Phase 4 (证书)
    ↓
Phase 5 (复查)
```

### 7.3 里程碑

| 里程碑 | 内容 | 时间 |
|--------|------|------|
| M1 | 题库管理基础功能 | 1周 |
| M2 | 评估流程优化 | 1周 |
| M3 | 成绩报表 | 1周 |
| M4 | 证书功能 | 1周 |
| M5 | 测试优化 | 1周 |

---

## 八、待评审问题

### 8.1 功能确认

| # | 问题 | 选项 |
|---|------|------|
| 1 | 题目抽取是否允许重复？ | A.不可重复 B.可重复（推荐） C.限制次数 |
| 2 | 追问方案选择？ | A.预置 B.实时 C.预置+降级（推荐） |
| 3 | 单题限时默认值？ | 默认300秒 |
| 4 | 总时长限制默认值？ | 默认1800秒 |

### 8.2 待扩展功能

- 多维度得分（当前为二元制）
- 组织架构动态调整
- 定时评估任务

---

## 九、验收标准

- [ ] 题库支持创建/编辑/审核/发布
- [ ] AI批量生成题目进入待审状态
- [ ] 评估可从题库维度均衡抽取
- [ ] 追问支持预置+降级
- [ ] 成绩按组织架构权限隔离
- [ ] 统计报表显示通过率/雷达图
- [ ] 通过后自动生成证书
- [ ] 证书可下载/验真
- [ ] 历史记录保留最近3次

---

## 十、技术要点

### 10.1 维度均衡算法

```typescript
function selectQuestions(bankId, count, dimensionRatio) {
  const dimensions = ['prompt', 'llm', 'ide', 'devPattern', 'workCapability'];
  const selected = [];
  const usedIds = new Set();

  // 轮询从各维度选取
  let dimIdx = 0;
  while (selected.length < count) {
    const dim = dimensions[dimIdx % dimensions.length];
    const available = allItems.filter(
      (i) => i.dimension === dim && !usedIds.has(i.id) && i.status === 'PUBLISHED'
    );

    if (available.length > 0) {
      // 高频题目优先
      const random = available.sort((a, b) => b.useCount - a.useCount)[0];
      selected.push(random);
      usedIds.add(random.id);
    }
    dimIdx++;
  }

  return selected;
}
```

### 10.2 追问降级策略

```typescript
function getFollowUp(question, userAnswer, followUpCount) {
  // 1. 检查预置追问
  if (question.predefinedFollowUps && followUpCount < question.predefinedFollowUps.length) {
    return question.predefinedFollowUps[followUpCount];
  }

  // 2. 降级：跳过追问
  return null; // 进入下一题
}
```

---

## 附录

### A. 相关文档

- `docs/plans/2026-04-18-l1-talent-assessment-design.md` - L1设计
- `docs/plans/2026-04-20-assessment-system-complete-plan.md` - 旧版计划

### B. 现有代码参考

- `server/src/assessment/` - 评估模块
- `web/components/views/AssessmentView.tsx` - 前端评估界面

---

**文档状态**: 待评审后定稿
**下一步**: 评审并确认各模块功能