7.6 KiB

Raw Blame History

求职者评分体系 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，以及解释版本 explanationVersion、参与覆盖 coverage 和固定可比性提示 comparabilityNotice。coverage.computableDimensions 与实际参与 overallScore 的维度严格一致，excludedDimensions 列出未参与原因。

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

返回单维度明细：原有 dimension、score、status、subScores[]、reasons[]、dataSources[]、updatedAt、rulesVersion，以及 displayName、whatItMeasures、interpretation、limitations[]、evidenceLevel、ruleContributions[]、improvementActions[]、explanationVersion、validity（仅 ABILITY 有明确有效期）和 calculatedAt。非法 dimension → 400/1001。

学生单维明细（仅 STUDENT 本人）。解释版本固定为 candidate-scoring-explanation-v1，与评分 rulesVersion 分离。ruleContributions 由真实计分分支产生，贡献之和可与最终维度分数对账；SCORE_CAP_ADJUSTMENT 用于说明 0–100 截断，SCORE_ROUNDING_ADJUSTMENT 仅记录逐项展示舍入与最终两位小数的对账差，不改变评分规则。dataSources 仅使用“个人教育资料”“求职偏好”“平台求职活动”“简历与技能资料”“Offer 履约与候选反馈”“四维能力测评”等产品语义名称。不返回 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)。不新增错误码。

N02 解释与合理性边界

本版只增强学生可见解释，不改变八维公式、12.50 默认权重、参与维度、candidate-scoring-v0.1/v0.2 切换、V32 排名或快照写入语义。
INTERNSHIP 未接入时保持 PENDING，不显示为 0 分；缺失维度仍退出综合分分母，综合卡通过 coverage 和 comparabilityNotice 明确提示不同参与集合不可直接横向比较。
规则解释为固定白名单模板，不接入 AI/LLM/SHAP，不把教育、平台行为、履约或活跃信号解释为人格、信用、确定性能力或录用结论。
企业评分接口 schema 保持不变，只返回既有聚合字段；解释、覆盖率、限制、建议、规则贡献和 ABILITY 有效期仅对学生本人可见。
Clock 在每次评分请求入口捕获一次 capturedNow，并用于时间窗口、ABILITY 有效期、calculatedAt 与快照时间；真实 MySQL/Docker 验收仍为本版发布前置条件。

7.6 KiB Raw Blame History