# 求职者评分体系 API

> 求职者评分体系（Candidate Scoring Engine）v0.1 · 规则版本 `candidate-scoring-v0.1`
> V38 起：功能开关 `scoring.ability-assessment.enabled`（默认 `false`）开启时，`ABILITY` 按 V36 四维能力测评的最新有效结果映射，候选评分规则版本升级为 `candidate-scoring-v0.2`；关闭时保持 `candidate-scoring-v0.1` 与既有 `ABILITY=PENDING` 行为。
> 基础路径：`/api/v1` · 全部接口需 `Authorization: Bearer <accessToken>`

## 概述

8 个确定性评分维度：`EDUCATION`、`INTERNSHIP`、`ABILITY`、`COMPLIANCE`、`STABILITY`、`GROWTH`、`INTEGRITY`、`ACTIVITY`。

- 全部为**确定性规则 + 统计计算**，不接入 AI / SHAP / 公平性 / 防刷算法。
- 评分查询会写入 `candidate_dimension_scores` 快照（原生 `INSERT ... ON DUPLICATE KEY UPDATE` 批量 upsert），**不修改任何业务表**。
- 八维默认权重均为 `12.50`，参与计算的维度重新归一化（overallScore = 可计算维度算术平均）。
- 分数精度：`BigDecimal`，scale=2，`HALF_UP`；无可计算维度时 `overallScore=null`。

## 维度状态

| 状态 | 含义 |
|---|---|
| `OK` | 输入齐备，按规则确定性计算 |
| `ESTIMATED` | 部分输入缺失，使用兜底值并标注估算（如学校未知、偏好字段部分填写） |
| `INSUFFICIENT_DATA` | 关键输入缺失，不计算（score=null） |
| `PENDING` | 数据源未就绪（INTERNSHIP 无实习表；ABILITY 无测评、仅有过期/结构异常结果或开关关闭），score=null |

综合卡 `status`：全部 8 维可计算→`OK`；部分可计算→`PARTIAL`；无可计算且存在 PENDING→`PENDING`；否则→`INSUFFICIENT_DATA`。

## 接口列表

### 1. GET `/profile/me/candidate-scoring`（仅 STUDENT 本人）

返回综合评分卡：`candidateId`、`status`、`overallScore`、`weights`、`dimensions[]`、`rulesVersion`、`generatedAt`。

### 2. GET `/profile/me/candidate-scoring/dimensions/{dimension}`（仅 STUDENT 本人）

返回单维度明细：`dimension`、`score`、`status`、`subScores[]`、`reasons[]`、`dataSources[]`、`updatedAt`、`rulesVersion`。非法 `dimension` → 400/1001。

> 学生单维明细（仅 STUDENT 本人）。V38 起 `dimensions[n]=ABILITY` 时，`subScores[]` 为四条白名单聚合分（逻辑能力/35、执行能力/30、学习能力/20、沟通能力/15），`dataSources[]/reasons[]` 仅表述“最新有效四维能力测评”“完成时间”“有效期”“映射规则版本”；**不返回** `sourceResultId`、答题/答卷 ID、题目、答案、答案键、选项分值、`competencyTag`、完整内部 `sub_scores_json`。其他维度响应与既有保持兼容。非法 `dimension` → 400/1001。

### 3. GET `/profile/me/candidate-scoring/trend?months=6`（仅 STUDENT 本人）

返回快照月度趋势（`months` 1–24，越界 400/1001）。每个 `period` 仅取该期 `OK/ESTIMATED` 维度重新归一化计算 `overallScore`，并携带该期 `rulesVersion`。

### 4. GET `/company/candidates/{applicationId}/scoring`（仅岗位所属企业）

企业只读评分卡。**仅返回** `applicationId`、`overallScore`、`status`、`dimensions[]{dimension,score,status}`、`generatedAt`、`rulesVersion`；**禁止返回** `studentUserId`、`candidateId`、`phone`、`email`、`resumeUrl`、`sub_scores` 细节、内部日志。V38 起等效于对 `ABILITY` 只暴露聚合 `score/status`，**禁止**返回 LOGIC/COMMUNICATION/EXECUTION/LEARNING 细分、`validUntil`、attemptId/resultId、`answerKey`、`scoringRule`、`questionCode`、`competencyTag`。

## 权限矩阵

| 接口 | 未登录 | STUDENT | COMPANY | ADMIN |
|---|---|---|---|---|
| 学生 3 接口 | 401 | ✅ 本人 | 403 | 403 |
| 企业评分 | 401 | 403 | ✅（岗位归属） | 403 |

企业归属校验：`companyRepository.findByOwnerUserId(jwtUserId)` → 无企业 403/2002 → `company.id.equals(job.companyId)` 不一致 403/8004 → application 不存在 404/8002。禁止比较 userId 与 companyId。

## 八维数据来源

| 维度 | 数据来源 |
|---|---|
| EDUCATION | student_profiles.education/school（学校档次用内置名单，未知→ESTIMATED 兜底 50） |
| INTERNSHIP | 数据源未就绪 → PENDING |
| ABILITY | 默认 `PENDING`；开关开启且有最新有效四维能力测评（WORKPLACE_ABILITY，COMPLETED、答题 24/24、`valid_until > capturedNow`）时按 `LOGIC×0.35 + EXECUTION×0.30 + LEARNING×0.20 + COMMUNICATION×0.15`（scale=2、HALF_UP）映射为 OK |
| COMPLIANCE | student_preferences（薪资/城市/用工/行业/岗位类型 5 字段加权；remoteAllowed 不计分） |
| STABILITY | users.createdAt（账号年龄）、applications（投递/撤回率）、audit_logs（近 30 天 LOGIN） |
| GROWTH | resume_versions（ACTIVE 数量/最近更新）、student_profiles.skillsJson（当前值，无历史） |
| INTEGRITY | offers/offer_status_history（ACCEPTED/EXPIRED）、candidate_feedback、资料完整度（student_profiles + ACTIVE 简历） |
| ACTIVITY | applications（近 90 天投递）、audit_logs（近 30 天活跃）、messages（发信） |

## 快照与趋势

- 表 `candidate_dimension_scores`：唯一约束 `(student_user_id, dimension, period)`；同周期覆盖、`version+1`；score/dimension/status 带 CHECK 约束。
- 趋势只读快照历史，不写快照；冷启动期通常仅当前月，随评分调用累积。

## 查询次数

- 综合卡：3 次实体读（user/profile/preference）+ 5 次 RowMapper 聚合（applications/audit/offers/feedback/resume）+ 1 次消息计数 + 1 次快照批量 upsert；全部单学生过滤，无 N+1，不按 8 维循环查库。
- 明细：同上（一次性采集，选单维）；趋势：快照按月聚合 1 条。

## 错误码

复用：`BAD_REQUEST(1001)`、`UNAUTHORIZED(2001)`、`FORBIDDEN(2002)`、`APPLICATION_NOT_FOUND(8002)`、`APPLICATION_OWNER_MISMATCH(8004)`。不新增错误码。