# 四维能力测评 API 设计文档（V36 设计锁定版）

> 状态：**设计已锁定，待编码**。功能版本 V36。题库为自研工作情境题；本版不接入候选评分引擎、不向企业开放结果。题目统计质量门槛保留为后续试测工作，不阻塞本版功能实现。

## 0. 产品来源摘要（func.xlsx，已确认）

- 功能名：**能力测评(4维度) = 逻辑 / 沟通 / 执行 / 学习 能力四维测评**（`功能详细清单 D24/F24`、`求职端功能详情 B24/C24`、`企业端功能详情`）。
- 目标：**了解自己目前的能力短板在哪里**（G24）。
- 结果展示：**四维能力测试 → 能力雷达图 + 短板提示**（F24）。
- 限时：**测评限时 30 分钟，超时强制提交**（G24）。
- 完成率：**测评完成率 ≥ 70%**（H24，中途退出保存进度的判定）。
- 质量：**测评区分度 ≥ 0.4**（H24/H52，为非功能质量门槛）。
- 能力测评评分（F1.2）：基于四维得分 → **能力综合分**，「让企业看到我的能力测评结果」；未测评显示「待测评」（G52）。
- 成长信号：学习能力/成长速度潜力分（F55/G55）。

## 1. 功能范围与非目标

**范围内（第一版 V36）**：
- 四维能力测评的题型目录、创建答卷、答题保存、进度恢复、提交、结果查询。
- 结果含四维分、综合分、最低维度短板提示、雷达图数据、题目解析与有效期状态。

**非目标（V36 默认不做，除非负责人确认）**：
- 不接入 Candidate Scoring / 不写 `candidate_dimension_scores`（ABILITY 保持 PENDING）。
- 不提供企业查看学生能力测评结果的接口。
- 不做岗位推荐、AI 路径建议、开放题或 AI 自动评分。
- 不做定时器批量改写结果有效期；结果是否过期在读取或新建答卷时由后端按 `valid_until` 动态判断。

## 2. 四个能力维度的正式名称与编码

| 编码(Code) | 名称 | 说明 |
|---|---|---|
| LOGIC | 逻辑能力 | 逻辑/推理/分析 |
| COMMUNICATION | 沟通能力 | 表达/协作/共情 |
| EXECUTION | 执行能力 | 行动/落地/结果导向 |
| LEARNING | 学习能力 | 学习/成长/适应 |

编码和结果字段按上表锁定。

## 3. 题库来源、题目数量、题目版本

- 题目来源：自研（`SELF_AUTHORED`），不复制商用量表。
- 锁定题库文件：`docs/ability-question-bank-v0.1.json`。迁移种子、题库测试和题目版本必须以该文件为唯一权威来源，禁止在 SQL 或 Java 中自行改写题干、选项、答案键、分值或解析。
- 题库总量：每维 12 题，共 **48 题**；每次答卷从每个维度分层随机抽取 6 题，共 **24 题**。
- 题型：单选题、情境判断题、排序题；允许选项部分得分，不采用开放题。
- 题目版本：`ability-v0.1`。每题必须保留 `difficulty`、`discrimination`、`version` 字段；前两项允许在首版种子数据中为空，试测后回填。

## 4. 是否固定题目或分层随机抽题

- 采用分层随机抽题：从每维 ACTIVE 题库随机抽取 6 题，并把题目集合、顺序、题目版本和题目快照持久化；刷新、恢复和重复读取均不得重新抽题。
- 新建或重测答卷均重新抽取本次 24 题；不得向前端返回内部维度、答案键、评分规则或题目版本。

## 5. 单次答题数量与完成条件

- 单次题量固定为 4 维 × 6 = **24 题**。
- 必须回答 24/24 才能提交；任何未完成答卷均返回 `ABILITY_INCOMPLETE`，不得依据 70% 生成正式结果。
- 产品“完成率 ≥ 70%”仅用于过程进度展示，不构成提交门槛。

## 6. 题型与计分规则

- 每题均为后端判分的工作情境题。每个选项对应 0、1、2 或 4 分；选项及其得分、标准答案键、评分规则和解析均只保存在后端。
- 每维原始分为该维 6 题得分之和，维度百分制分数为 `rawScore / 24 × 100`；保留两位小数，使用 `HALF_UP`。
- 综合分为四维百分制得分的等权平均；只有四维均完成 6 题时才生成综合分。
- 短板取最低维度；若最低分并列，返回全部并列维度。结果页同时返回每道题解析，但仅限答卷提交后由本人读取。

## 7. 中途保存和恢复规则

- 保存答案对 (attempt, question) upsert；同请求内同题重复 → 校验拒绝。
- 获取答卷恢复：固定题目顺序 + 已答值；刷新不重抽题。
- 未答完可退出，下次 GET 恢复；与 RIASEC 一致（active 答卷阻塞重测）。

## 8. 答卷状态机

锁定状态机：
```
DRAFT → IN_PROGRESS → COMPLETED
IN_PROGRESS --(超过 expires_at 且未提交)--> EXPIRED
```
- 创建答卷仅进入 `DRAFT`，不开始计时。
- 第一次成功保存答案时，后端一次性设置 `started_at=now`、`expires_at=started_at+30分钟`，并转为 `IN_PROGRESS`。
- 后续保存、读取、提交均由后端校验 `expires_at`；超时未答完 24 题时，原子标记为 `EXPIRED`，不生成结果、不可继续答题或提交。
- `DRAFT` 没有倒计时；同一学生同一类型始终至多存在一份 `DRAFT/IN_PROGRESS` 活跃答卷。

## 9. 重测和历史保留规则

- 历史答卷和结果永久保留，不删除。
- 完成时写入 `valid_until = completed_at + 7天`。在 `valid_until` 前为当前有效结果；到期后结果仍可查询，但 `validityStatus=EXPIRED` 且仅作为历史结果。
- 不设置“历史最高分”。当前结果只取最近一次已完成且仍有效的结果，避免用户通过反复答题刷取最高分。
- 有效结果存在期间禁止重测；结果到期后方可创建下一份答卷。
- 每名学生滚动 90 天内最多完成 3 次测评；未完成而超时的 `EXPIRED` 答卷不计入该完成次数。

## 10. 提交幂等与并发策略

- 唯一键：`(student_user_id, idempotency_key)` 幂等；`active_key`（学生+类型+ACTIVE）保证同类型最多 1 份活跃答卷（复用 V35 已验证方案）。
- 提交原子化：`DRAFT/IN_PROGRESS → COMPLETED` 的批量更新返回行数；仅行数=1 者生成结果+写审计；并发只产生 1 条 result + 1 条提交审计；重复提交幂等返回原结果。
- 提交并发无 500（沿用 V35 REQUIRES_NEW + READ_COMMITTED 修复）。
- 创建时先校验当前有效结果是否存在，再校验 90 天完成次数；两类限制须有对应错误码，不能误报为活跃答卷冲突。

## 11. 权限矩阵

| 接口 | 未登录 | STUDENT | COMPANY | ADMIN |
|---|---|---|---|---|
| 类型列表 | 401 | 200 | 200 | 200 |
| 创建 / 答卷 / 保存 / 提交 / 结果 / 历史 | 401 | 仅本人 | 403/2002 | 403/2002 |

- 身份一律 JWT/SecurityContext，不接受 userId 参数。
- 第一版不提供企业查看能力结果接口；能力综合分写入评分引擎与企业侧结果展示均为后续独立评审事项。

## 12. 错误码

- V35 RIASEC 已占用 `9701–9709`（97xx）。V36 使用独立区间 **`9801–9811`**（能力测评），避免复用冲突：
  - `9801 ABILITY_TYPE_NOT_FOUND`、`9802 ABILITY_ATTEMPT_NOT_FOUND`、`9803 ABILITY_ATTEMPT_INVALID_STATE`、`9805 ABILITY_ANSWER_INVALID`、`9806 ABILITY_INCOMPLETE`、`9807 ABILITY_CONCURRENT_UPDATE`、`9808 ABILITY_DUPLICATE_ACTIVE`、`9809 ABILITY_IDEMPOTENCY_CONFLICT`。
- `9810 ABILITY_RETAKE_COOLDOWN`（409）：当前仍存在有效完成结果，尚不可重测。
- `9811 ABILITY_RETAKE_LIMIT`（429）：滚动 90 天内已完成 3 次。
- 复用 `1001/2001/2002`；超时答卷读取、保存或提交统一按 `9803 ABILITY_ATTEMPT_INVALID_STATE` 处理。

## 13. DTO 与接口字段

接口采用独立 `/abilities/**` 命名空间（最终 7 个接口）：
```
GET  /abilities/types
POST /abilities/attempts
GET  /abilities/attempts/{attemptId}
PATCH /abilities/attempts/{attemptId}/answers
POST /abilities/attempts/{attemptId}/submit
GET  /abilities/attempts/{attemptId}/result
GET  /abilities/me?page&size
```
V36 不提供 `GET /abilities/{type}/questions`；题目只在创建答卷后通过 `GET /abilities/attempts/{attemptId}` 返回。
- 题目响应隐藏 `dimension/questionCode/competencyTag/source/reverseScored/questionVersion/answerKey/scoringRule`（不泄露能力维度语义与计分内部字段）。
- 结果响应（白名单）：`attemptId/typeCode/status/validityStatus/validUntil/dimensionScores[{code,score,answeredCount}]/overallScore/weaknesses/radar/answeredCount/completionRate/questionFeedback[{questionId,selectedOption,explanation}]/disclaimer`。不含答案键、选项得分、studentUserId、phone、email、password。

## 14. 数据库表、索引、唯一约束、外键

采用独立 `ability_*` 六表，避免与 V35 RIASEC 的题型、判分方式和生命周期耦合：
```
ability_definitions        type_code UNIQUE; status; scale_type; question_count; attempt_question_count; min_per_dimension; question_set_version; rules_version
ability_questions          UNIQUE(definition_id, question_code), UNIQUE(definition_id, position), CHECK(dimension IN LOGIC/COMMUNICATION/EXECUTION/LEARNING), item_type/options_json/answer_key_json/scoring_rule_json/explanation/difficulty/discrimination/version
ability_attempts           UNIQUE(student_user_id, idempotency_key), UNIQUE(active_key), @Version, CHECK(status IN DRAFT/IN_PROGRESS/COMPLETED/EXPIRED)
ability_attempt_questions  UNIQUE(attempt_id, question_id), UNIQUE(attempt_id, position), question_version/question_snapshot_json
ability_answers            UNIQUE(attempt_id, question_id), selected_option/awarded_score/answered_at
ability_results            UNIQUE(attempt_id)（幂等）
```
- 外键：attempt→definitions/users(CASCADE)、attempt_question/answer→attempt(CASCADE)+question、result→attempt(CASCADE)。题目快照用于保证题库后续修订或停用后，历史答卷和提交后的解析仍按当时版本展示与计分。
- 索引：`(student_user_id, created_at)`、`active_key` 唯一、`status` 等。
- 时间相关字段：`started_at/expires_at/submitted_at/completed_at`；结果含 `valid_until`。`active_key` 仅在 `DRAFT/IN_PROGRESS` 非空，进入 `COMPLETED/EXPIRED` 后置空。

## 15. 脱敏要求

- 题目响应不泄露维度与内部编码；结果不返回原始答案、手机号、邮箱、password、JWT、他人信息。
- 不保存不必要的题面；审计不含题面/答案/PII。

## 16. 审计要求

- 写入 `ABILITY_ATTEMPT_CREATED` / `ABILITY_ATTEMPT_SUBMITTED`。
- details 仅允许 `attemptId/typeCode/status/answeredCount/questionSetVersion/rulesVersion/requestId/timestamp`；禁止题面、答案、手机号、邮箱、JWT。

## 17. 是否写入 candidate_dimension_scores

- V36 第一版不写 `candidate_dimension_scores`，ABILITY 维度维持 `PENDING`；不提供企业端能力测评结果接口。
- 将能力综合分写入评分引擎、企业端查看结果均为后续独立评审事项。

## 18. OpenAPI 增量

- 基线 134 paths / 168 operations。
- 固定 +7 paths / +7 operations（`/abilities/**` 7 端点：类型/创建/详情/保存/提交/结果/我的历史）→ **141 paths / 175 operations**；V36 不提供 `GET /abilities/{type}/questions`。运行时 OpenAPI 必须与静态一致。

## 19. MockMvc、集成测试和 MySQL 黑盒验收方案

- 测试类（镜像 RIASEC）：
  - `AbilityAssessmentCatalogTest`、`AbilityAssessmentResultComputerTest`、`AbilityAssessmentAttemptServiceTest`、`AbilityAssessmentControllerTest`、`AbilityAssessmentPersistenceIntegrationTest`（含并发创建/并发提交）、种子/迁移测试。
- 覆盖：创建、幂等重放、同 key 同/异请求、活跃重复、有效结果冷却、90 天完成上限、中途保存、首次保存起算、恢复同一题、30 分钟超时、非法/跨答卷题 ID、未答完提交、重复提交、并发创建/提交、STUDENT/COMPANY/ADMIN/匿名权限、结果和题目解析脱敏、业务表无异常写入、Flyway、外键/唯一约束。
- MySQL 黑盒：健康 200、Flyway 最新成功、运行时/静态 OpenAPI 一致、表/约束/数据核验、并发无 500、审计脱敏、队列归零、`candidate_dimension_scores` 行数不变、V31–V35 回归。

## 20. 回滚与兼容方案

- 不修改 V1–V35 表与语义；V36 迁移为附加新表 `V35__ability_assessment.sql`（当前最新 Flyway 为 V34，下一编号为 V35；功能版本仍标 V36）。
- 回滚：删除 V36 迁移即可，不影响 V35 及既有数据。
- 使用独立 `/abilities/**` 命名空间与独立 `ability_*` 表，回滚不会影响 V35 RIASEC。

---

## 21. 试测与上线声明

- 首版 48 题必须在后续试测中统计难度、选项分布与区分度；区分度低于 0.4 或存在明显歧义的题目应修改、停用或替换。
- 当前未定义试测样本量和正式上线统计门槛，因此本版不得宣称题库已完成心理测量学验证。
- 结果页必须声明：本测评反映当前工作情境答题表现，用于自我了解和能力提升参考；不构成职业资格、正式招聘结论或永久能力标签。

> 本设计已由负责人确认，可进入 V36 编码；试测统计口径为后续运营与题库质量治理工作，不阻塞本版实现。