feat: implement QuestionBank CRUD with pagination and template query

- Add pagination support to findAll (page, limit query params) - Add findByTemplateId method to service - Add GET /by-template/:templateId endpoint to controller - Service already includes CRUD for QuestionBank and QuestionBankItem
2026-04-23 17:19:11 +08:00
commit 0a9588abb7
492 changed files with 112453 additions and 0 deletions
@@ -0,0 +1,522 @@
+# 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项确认内容 |
+
+### D. 评审确认内容（v2.0）
+
+1. 模板新增 `dimensionQuota` 字段配置各维度数量
+2. 审核改为单题逐审（可批量选择操作）
+3. 超时不记分（不影响得分）
+4. 中断超时强制提交
+5. 统计准实时（缓存5分钟）
+6. 复查只能调整最终总分
+7. 同一模板只保留首次通过证书
+8. 证书仅预览不可下载
+9. 模板一对一题库
+10. 复查不影响已发证书（保持不变）
+
+---
+
+**文档状态**: ✅ 最终版（评审通过）
+**下一步**: 进入实施阶段