# V42 企业人才邀约与授权沟通 API

V42 允许已认证企业使用 V41 生成的 `candidateKey` 向开放人才候选人发起站内邀约；学生明确接受后才建立 `TALENT_INVITATION` 会话。候选人身份、测评明细和联系方式始终不向企业公开。

## 接口清单

| 方法 | 路径 | 身份 | 说明 |
| --- | --- | --- | --- |
| POST | `/companies/me/jobs/{jobId}/talent-invitations` | 已认证 COMPANY | 创建邀约 |
| GET | `/companies/me/talent-invitations` | 已认证 COMPANY | 分页查看本公司邀约 |
| GET | `/companies/me/talent-invitations/{invitationId}` | 已认证 COMPANY | 查看本公司邀约详情 |
| GET | `/profile/me/talent-invitations` | STUDENT | 分页查看本人收到的邀约 |
| GET | `/profile/me/talent-invitations/{invitationId}` | STUDENT | 查看本人邀约详情 |
| POST | `/profile/me/talent-invitations/{invitationId}/decision` | STUDENT | 接受或拒绝邀约 |

V42 新增 6 个 path、6 个 operation；静态 OpenAPI 基线为 167 paths / 205 operations。

> 验收状态：真实 MySQL/Docker 黑盒通过（`PASS=76 / FAIL=0`）；运行时与静态 OpenAPI 均为 167 paths / 205 operations，待 Git 检查点。

## 创建邀约

```json
{
  "candidateKey": "V41-generated-opaque-key",
  "message": "欢迎了解我们的后端开发岗位。",
  "idempotencyKey": "3c989a31-6774-4520-9700-e58416cc1845"
}
```

服务端重新确认企业认证、岗位归属和 `PUBLISHED` 状态、岗位画像 `enabled=true && APPROVED`、候选授权、账号状态、当前企业全部历史投递排除和至少一个有效信号。`candidateKey` 按 V41 相同密钥、时区和日期桶重算，并使用常量时间比较；请求不得携带学生 ID。

邀约有效期为 7 天。相同公司和幂等键的相同请求返回原邀约，不重复占用限额；同键不同业务内容返回 `409/10207`。每公司每岗位每天最多 20 次、每公司每天最多 100 次成功创建；同企业同学生终态后 30 天内不可再次邀约。

`message` 去首尾空白后为 1–300 字符，禁止手机号、邮箱、URL、微信/QQ 等外部联系方式。无效文案统一返回 `400/10208`，不写入邀约。

## 学生决策

```json
{
  "decision": "ACCEPT",
  "expectedVersion": 0
}
```

只有未过期 `PENDING` 可决策。`ACCEPT`、`REJECT`、到期 `EXPIRED` 采用条件更新和版本控制；并发请求只有一方能改变状态。接受时若任一方向存在屏蔽，返回 `403/2002` 且保持 `PENDING`。接受成功后在同一事务中创建唯一会话和两条成员记录；拒绝、过期不创建会话。

学生详情包含 `version`，只有 `ACCEPTED` 返回 `conversationId`。企业端不返回 `candidateKey`、`studentUserId`、`candidateKeyDigest`、`activeKey`、测评/评分字段或拒绝内部原因。

## 会话隐私

`TALENT_INVITATION` 会话仅由接受流程的内部组件创建，不开放传学生 ID 的公网入口。既有 `DIRECT` 会话的 MATCHED 守卫保持不变。会话、消息列表和发送响应对邀约会话仅返回 `CURRENT_USER`/`OTHER_PARTICIPANT` 相对身份，不返回 `createdBy` 或 `senderUserId`，也不提供学生姓名、联系方式或简历信息。

## 错误码

`10201` 不存在或无权查看；`10202` 候选当前不可邀约；`10203` 活跃/冷却冲突；`10204` 状态不允许决策；`10205` 已过期；`10206` 版本或条件更新冲突；`10207` 幂等键业务内容冲突；`10208` 请求或文案非法；`10209` 达到每日限额。角色、归属和屏蔽继续使用 `401/2001`、`403/2002`。

## 事务与数据边界

创建事务先锁定公司行，再执行幂等、冷却、限额和写入；数据库唯一约束作为最终防线。过期转换使用独立事务，确保 `EXPIRED`、释放 `activeKey`、history 和审计先提交再返回错误。V42 不写 `candidate_dimension_scores`，不发送 RabbitMQ 通知，不保存候选人联系方式或正文以外的敏感数据。