qingsongping-AIDevelop/docs/candidate-scoring-api.md

求职者评分体系 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)。不新增错误码。