shz-backend/docs/app-interview-rtc-api.md

面试视频房间接口

1. 接口说明

本组接口用于创建一场面试视频通话，并分别获取面试官和候选人的 MyRTC 连接凭据。

后端会在一次请求中完成以下操作：

1. 自动生成一个唯一的 roomId；
2. 生成面试官专用的 peerId；
3. 生成候选人专用的 peerId；
4. 使用与 MyRTC 服务一致的 JWT 密钥，分别签发两枚一次性 token；
5. 保证两枚 token 绑定同一个 roomId。

前端不需要调用房间详情查询和房间销毁接口。房间在 MyRTC 客户端成功执行 join 后创建；双方离开后由 MyRTC 自动回收空房间。

2. 创建房间并获取双方凭据

请求

POST /app/interview/rtc/token
Authorization: Bearer <业务系统登录Token>
Content-Type: application/json

请求体为空即可，不需要传入 roomId、peerId 或 token。

{}

成功响应

接口遵循后端统一的 AjaxResult 返回格式：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "roomId": "room-0a4c3fbd8f9e4b70a0e2de99f6b5f2a8",
    "expiresIn": "5m",
    "interviewer": {
      "role": "interviewer",
      "peerId": "interviewer-4a78d8f0c4a5468fb0d8d05a8199b3bb",
      "token": "eyJhbGciOiJIUzI1NiJ9..."
    },
    "candidate": {
      "role": "candidate",
      "peerId": "candidate-1d2f7e2e2ae8462da3bb514d2f39b8e3",
      "token": "eyJhbGciOiJIUzI1NiJ9..."
    }
  }
}

字段说明：

字段	类型	说明
code	number	200 表示成功
msg	string	接口提示信息
data.roomId	string	本次面试房间 ID，双方必须使用同一个值
data.expiresIn	string	token 有效期，当前通常为 5m
data.interviewer.role	string	固定为 interviewer
data.interviewer.peerId	string	面试官在该房间内的唯一 ID
data.interviewer.token	string	面试官的一次性 MyRTC JWT
data.candidate.role	string	固定为 candidate
data.candidate.peerId	string	候选人在该房间内的唯一 ID
data.candidate.token	string	候选人的一次性 MyRTC JWT

3. 前端使用流程

3.1 调用后端接口

const response = await request.post('/app/interview/rtc/token', {})

if (response.code !== 200) {
  throw new Error(response.msg || '创建面试视频房间失败')
}

const session = response.data

const roomId = session.roomId
const interviewer = session.interviewer
const candidate = session.candidate

注意：roomId 在响应的 data.roomId 中，不是在响应最外层。

3.2 面试官加入房间

面试官客户端使用：

{
  roomId: session.roomId,
  peerId: session.interviewer.peerId,
  token: session.interviewer.token
}

3.3 候选人加入房间

候选人客户端使用：

{
  roomId: session.roomId,
  peerId: session.candidate.peerId,
  token: session.candidate.token
}

两端的 roomId 必须完全相同，但 peerId 和 token 必须使用各自对应角色的数据，不能交叉使用。

4. MyRTC WebSocket 连接参数

MyRTC 的 WebSocket 地址由 MyRTC 服务部署地址决定。当前服务的信令路径是 /signaling，JWT 通过 WebSocket 握手阶段的 token 查询参数传入，例如：

wss://rtc.zhaopinzao8dian.com/signaling?token=<url-encoded-token>

如果使用 WebSocket 原生 API，建议使用 URL 对 token 做编码，不要直接拼接未编码的 token：

const wsUrl = new URL('wss://rtc.zhaopinzao8dian.com/signaling')
wsUrl.searchParams.set('token', token)
const ws = new WebSocket(wsUrl.toString())

加入房间时，发送的业务消息需要包含 roomId、peerId 和 token。协议形式如下：

{
  "type": "request",
  "action": "join",
  "requestId": "join-001",
  "payload": {
    "roomId": "room-0a4c3fbd8f9e4b70a0e2de99f6b5f2a8",
    "peerId": "interviewer-4a78d8f0c4a5468fb0d8d05a8199b3bb"
  }
}

token 通常在建立 WebSocket 连接时通过 SDK 配置或连接参数传入，不能把面试官 token 和候选人 token 互换。

如果使用项目已有 MyRTC SDK，前端只需要将以下三个字段传给 SDK：

await rtcClient.connect({
  roomId,
  peerId,
  token
})

5. token 注意事项

• token 是一次性的，成功 join 后即会被 MyRTC 消费；
• token 默认有效期为 5m，过期后不能继续使用；
• 页面刷新或连接断开后重新连接，不能继续复用已经成功 join 的 token，需要重新调用后端接口签发；
• 面试官和候选人的 token 绑定不同的 peerId，不能让两个客户端使用同一组凭据；
• roomId、peerId 和 token 应保存在当前面试页面的内存状态中，不建议写入长期本地存储；
• 前端不需要保存或传递 MyRTC 的 ADMIN_TOKEN，该令牌只由业务后端访问 MyRTC 控制面时使用。

6. 错误响应

未登录

{
  "code": 500,
  "msg": "未登录"
}

MyRTC JWT 密钥未配置或配置不一致

后端可能返回类似以下错误：

{
  "code": 500,
  "msg": "MyRTC JWT_SECRET 未配置"
}

如果后端签发 token 使用的密钥和 MyRTC 服务配置不一致，前端会在连接或 join 阶段收到 token 签名错误。此时需要检查业务后端和 MyRTC 的 JWT_SECRET 是否完全一致。

MyRTC 服务不可用

{
  "code": 500,
  "msg": "无法连接 MyRTC"
}

7. 房间查询和销毁接口

这两个接口不是前端视频通话流程的一部分，前端无需调用：

GET    /app/interview/rtc/room/{roomId}
DELETE /app/interview/rtc/room/{roomId}

它们仅供后端管理或运维场景使用。正常情况下，前端只需要：

POST /app/interview/rtc/token

然后使用响应中的双方凭据加入同一个 roomId 即可。