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

> **文档状态**: ✅ 评审通过
> **创建日期**: 2026-04-23
> **版本**: 2.0
> **评审日期**: 2026-04-23

---

## 一、系统概述

### 1.1 目标

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

### 1.2 核心流程

```
知识库 → 模板配置 → 题库（AI生成+审核） → 评估抽取 → 用户答题 → 评分 → 成绩 → 证书
                                                          ↑
                                                    复查（调整总分）
```

### 1.3 评估发起模式

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

---

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

### 2.1 组织结构

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

### 2.2 角色权限矩阵

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

### 2.3 权限规则

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

---

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

### 3.1 功能清单

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 创建题库 | 关联知识库，关联模板（一对一），设定题目范围 | P0 |
| 单题管理 | 增删改查，支持简答/选择/判断 | P0 |
| AI批量生成 | 按模板dimensionQuota配置生成待审题目 | 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 模板与题库关联

- **方案**：一对一关系（模板→单一题库）
- 题库不单独关联知识库，由模板指定知识库范围
- 模板配置 `dimensionQuota` 字段指定各维度题目数量

### 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;
  status: enum;                // PENDING_REVIEW/PUBLISHED
}
```

### 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/:bankId/items/: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 |
| 中断处理 | 超时强制提交 | P0 |
| 成绩判定 | ≥6分通过 | P0 |

### 4.2 题目抽取算法

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

### 4.3 追问机制

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

### 4.4 时间控制

| 限制 | 默认值 | 超时处理 |
|------|--------|---------|
| 单题限时 | 300秒 | 超时不记分，自动下一题 |
| 总时长限制 | 1800秒 | 超时强制提交 |

### 4.5 中断处理

- 评估进行中中断，超时强制提交
- 已答题目计入成绩，超时题目不记分

### 4.6 评估流程

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

### 4.7 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分钟） | P1 |

### 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 复查规则

- 讲师只能调整最终总分
- 复查记录可追溯
- **复查不影响已发证书**（保持不变）

### 5.5 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 |
| 证书预览 | 仅预览，不可下载 | P1 |
| 证书验真 | 二维码/ID查询 | P1 |

### 6.2 证书内容

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

### 6.3 证书唯一性规则

- **同一模板只保留第一次通过的证书**
- 后续通过同一评估不生成新证书
- 复查后分数变化不影响已发证书

### 6.4 有效期

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

### 6.5 证书展示

- 仅提供预览功能，不提供下载
- 可通过二维码或证书ID验证真伪

### 6.6 证书样式

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

### 6.7 API设计

```typescript
// 证书
GET    /api/assessment/:id/certificate         // 获取证书（预览）
POST   /api/assessment/certificate/verify       // 验证证书
```

---

## 七、实施计划

### 7.1 任务分解

| Phase | Task | 内容 | 优先级 |
|-------|------|------|--------|
| 1 | A1 | 题库实体创建（关联模板一对一） | P0 |
| 1 | A2 | 题目实体创建 | P0 |
| 1 | A3 | 题库Service/Controller | P0 |
| 1 | A4 | AI批量生成（按dimensionQuota配置） | P0 |
| 1 | A5 | 单题审核流程 | P0 |
| 2 | B1 | 题目抽取算法（维度均衡/高频优先） | P0 |
| 2 | B2 | 评估流程接入题库 | P0 |
| 2 | B3 | 追问预置+降级 | P0 |
| 2 | B4 | 时间控制（超时不记分） | P1 |
| 2 | B5 | 中断超时强制提交 | P0 |
| 3 | C1 | 统计API（缓存5分钟） | P1 |
| 3 | C2 | 报表前端 | P1 |
| 3 | C3 | 历史管理（保留3次） | P1 |
| 3 | C4 | 导出功能 | P1 |
| 3 | C5 | 复查功能（只调总分） | P2 |
| 4 | D1 | 证书实体 | P1 |
| 4 | D2 | 证书生成（首次通过才发） | P1 |
| 4 | D3 | 证书预览 | P1 |
| 4 | D4 | 证书验真 | P1 |

### 7.2 执行顺序

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

### 7.3 里程碑

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

---

## 八、验收标准

- [ ] 题库支持创建/关联模板（一对一）/���辑/单题审核/发布
- [ ] AI批量生成题目按dimensionQuota配置
- [ ] 评估可从题库维度均衡抽取
- [ ] 追问支持预置+降级
- [ ] 超时不记分，中断超时强制提交
- [ ] 成绩按组织架构权限隔离
- [ ] 统计准实时（缓存5分钟）
- [ ] 历史记录保留最近3次
- [ ] 复查只能调整总分，不影响已发证书
- [ ] 通过后生成证书（首次通过才发）
- [ ] 证书仅预览不可下载
- [ ] 证书可验真（二维码/ID）

---

## 九、闭环确认

### 数据流闭环

```
知识库 → 模板 → 题库（AI生成+单题审核）→ 评估抽取 → 用户答题 → 评分 → 成绩 → 证书
                                                          ↑
                                                    复查（调总分）
```

### 关键闭环点

| 检查点 | 确认 |
|--------|------|
| 知识库→题库 | ✅ AI生成题目关联知识库 |
| 题库→评估 | ✅ 按模板（一对一）抽取已发布题目 |
| 评估→成绩 | ✅ 答题后记录成绩 |
| 成绩→证书 | ✅ 首次通过后生成证书 |
| 复查→成绩 | ✅ 讲师可调整总分 |
| 复查→证书 | ✅ 不影响已发证书 |

---

## 附录

### 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` - 前端评估界面

### C. 评审记录

| 日期 | 版本 | 变更内容 |
|------|------|----------|
| 2026-04-23 | 1.0 | 初稿 |
| 2026-04-23 | 2.0 | 评审通过，更新10项确认内容 |
| 2026-06-16 | **3.0** | **实施修正** — 详见下方实施修正记录 |

### D. 评审确认内容（v2.0）

1. 模板新增 `dimensionQuota` 字段配置各维度数量
2. 审核改为单题逐审（可批量选择操作）
3. 超时不记分（不影响得分）
4. 中断超时强制提交
5. 统计准实时（缓存5分钟）
6. 复查只能调整最终总分
7. 同一模板只保留首次通过证书
8. 证书仅预览不可下载
9. 模板一对一题库
10. 复查不影响已发证书（保持不变）

---

## 十、实施修正记录（v3.0）

> 以下内容记录了从 v2.0 设计评审到实际实施过程中的**修正与增补**。

### 10.1 题目抽取算法修正

**原设计**（v2.0 4.2节）：

```typescript
function selectQuestions() {
  // 按dimensionQuota配置的比例抽取
  // Math.round(...)
}
```

**问题**：`Math.round` 导致合计偏差，如 3题→4题、5题→6题、7题→6题。

**修正为**（`question-bank.service.ts`）：

```typescript
function selectQuestions() {
  // floor + remainder 分配法，保证总和恒等于 count
  // 1. 各维度 target = floor(count × weight / totalWeight)
  // 2. remainder = count - sum(targets)，按 weight 降序分配
  // 3. 各维度池 shuffle 后抽 target 道
  // 4. 不足时从剩余池随机补足（保留维度标签日志）
}

// 验证结果:
// 20题 → PROMPT:6 + LLM:6 + IDE:4 + DEV_PATTERN:4 = 20 ✅
// 10题 → PROMPT:3 + LLM:3 + IDE:2 + DEV_PATTERN:2 = 10 ✅
//  5题 → PROMPT:2 + LLM:1 + IDE:1 + DEV_PATTERN:1 = 5  ✅
```

### 10.2 P0 — 答题体验优化（新增）

实施过程中新增以下前端功能：

| 功能 | 说明 | 实现位置 |
|------|------|---------|
| **题序导航点** | 顶部圆点：当前题蓝色、已标记黄色、其他灰色 | `AssessmentView.tsx` |
| **标记回头检查** | 🏷️ 按钮标记当前题，导航点变黄，方便回头检查 | `AssessmentView.tsx` |
| **提交确认弹窗** | 未答完时提交弹出确认对话框，防止误提交 | `AssessmentView.tsx` |

### 10.3 P1 — 题库管理增强（设计补充）

**原设计**：题库与模板为一对一关系。

**实施补充**：

| 变更 | 说明 | 文件 |
|------|------|------|
| `tags` 字段 | QuestionBankItem 新增 `tags` JSON 数组，支持多标签过滤 | `question-bank-item.entity.ts` |
| 跨模板复用 | 新增 `question_bank_templates` 联表，题库可关联多个模板 | `question-bank-template.entity.ts` |

### 10.4 P2 — 考试配置增强（新增）

| 新字段 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `attemptLimit` | int | 1 | 最大尝试次数，0=不限 |
| `scheduledStart` | datetime | null | 预约开始时间 |
| `scheduledEnd` | datetime | null | 预约结束时间 |
| `reviewMode` | string | 'none' | 回顾模式：none / after_completion |
| `shuffleQuestions` | boolean | true | 是否每题随机排序 |

**实现要点**：
- `startSession()` 中校验 attemptLimit、scheduledStart/End
- `getSessionState()` 根据 reviewMode 控制答案可见性
- 新增 `GET /assessment/:id/review` 回顾端点
- `selectQuestions()` 返回后根据 shuffleQuestions 做 Fisher-Yates 洗牌

### 10.5 系统角色权限保护（缺陷修正）

**问题**：`PermissionService.setRolePermissions()` 未检查 isSystem，系统角色权限可通过 API 修改。

**修正**：增加 `if (role.isSystem) throw Error`。

### 10.6 GET /users/:id 端点缺失（缺陷修正）

**问题**：`UserController` 缺少 `@Get(':id')` 端点。

**修正**：新增 `findOne()` 方法，受 `@Permission('user:view')` 保护。

### 10.7 题库维度与评分标准修正

| 修正 | 说明 |
|------|------|
| 维度标签修复 | 会议记录题从 `PROMPT` → `LLM`（AI注意力机制问题） |
| 补充评分标准 | 为151道简答题补充 `judgment` 字段，AI评分有据可依 |
| 新增24题 | 覆盖AI安全使用指南（三大边界）、开发范式（SDD/Flow State/Vibe Coding）、L1评估检查清单 |

### 10.8 模板配置修正

| 模板 | v2.0设计 | 实际修正 |
|------|---------|---------|
| AI协作技巧-对话测评 | 4题 | **20题**（题数可配，模板编辑页面可调） |
| AI协作-非技术人员测评 | 不存在 | **新增**：PROMPT 50% / LLM 30% / WORK_CAPABILITY 20%，10题 |

### 10.9 测试覆盖（新增）

| 测试套件 | 项数 | 覆盖内容 |
|---------|:----:|---------|
| `test-systematic.mjs` | 142 | 全角色全维度系统测试 |
| `test-full-coverage.mjs` | 52 | 未覆盖路径补全回归 |
| `test-assessment-smoke.mjs` | 29 | 快速烟雾测试 |
| `test-e2e-assessment-full-flow.mjs` | 29 | 端到端全流程（登录→模板→题库→考核→评分→证书） |
| `test-p2-advanced.mjs` | 20 | P2高级功能专项 |
| `test-concurrent-assessments.mjs` | — | 20人并发考核 |
| `tests/full-assessment.e2e.spec.ts` | 18 | Playwright三Agent框架测试 |
| 3个旧测试脚本 | 94+42+— | 用户生命周期、权限验证、多轮对话 |

**总测试项**: ~340+ 项  
**总通过率**: ~99%

---

**文档状态**: ✅ 已实施（v3.0）
**维护部门**: AI推进部
**最近更新**: 2026-06-16