lxq/docs/enterprise-talent-discovery-api.md

V41 企业人才发现 API

V41 提供学生显式授权和企业岗位候选人发现。学生授权默认关闭；企业必须已认证，岗位必须属于当前企业、处于 PUBLISHED，并且具有 V39 enabled=true、APPROVED 的岗位画像。

接口

方法	路径	权限
GET	/profile/me/talent-discovery	STUDENT，仅本人
PUT	/profile/me/talent-discovery	STUDENT，仅本人
GET	/companies/me/jobs/{jobId}/talent-recommendations	已认证 COMPANY，且岗位属于本人

统一前缀为 /api/v1。身份从 JWT subject 获取，客户端不得传 studentUserId、companyId 或 candidateId。

学生开关

无记录的 GET 返回 enabled=false、version=0，不会自动写库。PUT 请求体：

{"enabled":true,"expectedVersion":0}

expectedVersion 可省略；已有记录传入后必须匹配当前版本。并发冲突复用 409/9201。成功只记录 TALENT_DISCOVERY_PREFERENCE_UPDATED，审计 details 仅包含 enabled/version/requestId。

企业候选列表

page 从 0 开始，size 为 1–50。岗位画像不可用时返回 mode=UNAVAILABLE；没有合格候选时返回 mode=NO_ELIGIBLE_CANDIDATE。正常返回 mode=PERSONALIZED。

候选池排除：未授权学生、注销限制账号、无基础档案、曾向当前企业任一岗位投递过的学生（包括 WITHDRAWN/REJECTED）。其他企业的投递不影响当前企业发现。

PREFERENCE/RIASEC/ABILITY 三个信号按 40/35/25 计算，缺失信号不按 0 处罚而重新归一化；至少一个有效信号才进入列表。RIASEC 和能力只读取最新完成结果，能力结果还必须未过期；不读取答案、题目、答案键、评分规则或标签。服务端先计算全部候选并全局排序，再分页，保证分页正确。

企业候选卡仅返回：

{
  "candidateKey":"…",
  "candidateLabel":"开放人才候选人",
  "city":"合肥",
  "education":"本科",
  "graduationYear":2027,
  "skills":["Java","Spring Boot"],
  "fitBand":"HIGH",
  "summary":"岗位画像与候选人公开资料存在较高匹配度",
  "signalsAvailable":["PREFERENCE","RIASEC","ABILITY"]
}

不返回学生 ID、姓名、联系方式、简历、测评分数、候选评分、结果/答卷 ID 或岗位画像原始权重。candidateKey 为 HMAC-SHA256、按公司/岗位/学生/日期桶隔离的不透明展示键，本版没有用它换取详情或联系方式的接口。

版本与边界

V41 新增 Flyway V39__enterprise_talent_discovery.sql，不修改 V1–V38，不写 candidate_dimension_scores，不新增 feature flag、ErrorCode、消息或推荐历史。OpenAPI 由 159/196 增至实际 161/199（两个唯一 path、三个 operation）。自动化测试 1461/1461 通过；真实 MySQL/Docker 黑盒已通过（PASS=37 / FAIL=0）。