# Voice Room Client API Flow

本文定义用户进入语音房后的客户端接口调用顺序、触发条件和服务边界。本文只描述 App 侧要调用的 gateway HTTP 接口、腾讯云 IM/RTC SDK 动作，以及不能由客户端直接调用的内部守卫接口。

## Scope

| Area | Owner | Rule |
| --- | --- | --- |
| HTTP 入口 | `gateway-service` | 鉴权、profile gate、协议转换、腾讯 IM/RTC token 签发 |
| 房间业务状态 | `room-service` | Room Cell、presence、麦位、房管、snapshot、outbox |
| 房间长连接和公屏 | 腾讯云 IM SDK | 客户端登录、房间群、公屏、系统消息接收 |
| 真实音频频道 | 腾讯云 RTC SDK | 进 RTC 房、切换 audience/anchor、发音频 |
| 用户主数据 | `user-service` | 登录、资料完成状态、用户区域、push token |

关键边界：

- 客户端进入语音房必须先 `JoinRoom` 写入 room-service 业务 presence，再进 IM 群和 RTC 房。
- `room-service` 不保存客户端 socket，也不保存腾讯云 RTC 连接态。
- 腾讯云 IM 群成员关系不是业务 presence；是否允许进群、发言、签 RTC token 仍以 room-service 守卫为准。
- gateway 只使用 access token 中的 `user_id` 作为 actor，客户端不能自报 `actor_user_id`、`owner_user_id`、`host_user_id`。
- 所有 `/api/v1` 业务响应使用 `{code,message,request_id,data}` envelope。

## Minimal Enter Room Flow

```mermaid
sequenceDiagram
  participant C as Client
  participant G as gateway-service
  participant R as room-service
  participant IM as Tencent IM SDK
  participant RTC as Tencent RTC SDK

  C->>G: POST /api/v1/rooms/join
  G->>R: JoinRoom(actor_user_id from token)
  R-->>G: room snapshot + user presence
  G-->>C: room snapshot

  C->>G: GET /api/v1/im/usersig
  G-->>C: IM user_sig
  C->>IM: login(user_id, user_sig)
  C->>IM: joinGroup(room_id)

  C->>G: POST /api/v1/rtc/token
  G->>R: VerifyRoomPresence(room_id, user_id)
  G-->>C: RTC user_sig, str_room_id, role=audience
  C->>RTC: enterRoom(strRoomId, audience)

  loop while room page is active
    C->>G: POST /api/v1/rooms/heartbeat
  end
```

### Required Order

| Step | Interface | Required | Reason |
| --- | --- | --- | --- |
| 1 | `POST /api/v1/rooms/join` | yes | 建立业务 presence，后续 IM/RTC 守卫依赖它 |
| 2 | `GET /api/v1/im/usersig` | yes | 登录腾讯云 IM，接收房间群消息和系统事件 |
| 3 | Tencent IM SDK `login` + `joinGroup` | yes | 本仓库不承载房间长连接 |
| 4 | `POST /api/v1/rtc/token` | yes for voice room audio | 签发 TRTC 票据；当前返回 `role=audience` |
| 5 | Tencent RTC SDK `enterRoom` | yes for voice room audio | 进入真实音频频道旁听 |
| 6 | `POST /api/v1/rooms/heartbeat` | yes | 刷新业务 presence，避免 stale timeout |

如果产品允许“只看公屏不听语音”，第 4、5 步可以延迟到用户打开音频时。但语音房默认应进入 RTC audience，以保证打开房间即可听到声音。

## Core Interfaces

### Join Room

```http
POST /api/v1/rooms/join
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_join_<room_id>_<user_id>_<nonce>",
  "role": "audience"
}
```

Response `data`:

```json
{
  "result": {
    "applied": true,
    "room_version": 2,
    "server_time_ms": 1778000000000
  },
  "user": {
    "user_id": 10001,
    "role": "audience",
    "joined_at_ms": 1778000000000,
    "last_seen_at_ms": 1778000000000
  },
  "room": {}
}
```

Rules:

- `room_id` 必须来自房间列表、分享或恢复接口，不能由客户端拼业务含义。
- `command_id` 用于房间命令幂等；客户端重试同一次进房必须复用同一个值。
- `role` 只作为展示默认值，不能通过自报 `admin/host/owner` 获得权限。
- JoinRoom 成功后才能登录 IM 进群和获取 RTC token。

### IM UserSig

```http
GET /api/v1/im/usersig
Authorization: Bearer <access_token>
```

Response `data`:

```json
{
  "sdk_app_id": 20036101,
  "user_id": "10001",
  "user_sig": "xxx",
  "expire_at_ms": 1778086400000
}
```

Rules:

- 当前 gateway 路由是 `GET /api/v1/im/usersig`。
- `user_id` 是内部不可变长 `user_id` 的十进制字符串，必须直接作为腾讯云 IM identifier。
- UserSig 只用于腾讯云 IM SDK 登录，不用于本仓库鉴权。
- 未完成资料用户会被 profile gate 拒绝。

Client SDK action:

```text
Tencent IM SDK login(user_id, user_sig)
Tencent IM SDK joinGroup(room_id)
```

### RTC Token

```http
POST /api/v1/rtc/token
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx"
}
```

Response `data`:

```json
{
  "sdk_app_id": 20036101,
  "user_id": "10001",
  "rtc_user_id": "10001",
  "user_sig": "xxx",
  "expire_at_ms": 1778007200000,
  "room_id": "lalu_xxx",
  "rtc_room_id": "lalu_xxx",
  "rtc_room_id_type": "string",
  "str_room_id": "lalu_xxx",
  "app_scene": "voice_chat_room",
  "role": "audience"
}
```

Rules:

- gateway 会先调用 room-service `VerifyRoomPresence`，用户不在房间、被踢、被 ban 时不会签发 RTC token。
- 当前只支持 TRTC `strRoomId`，客户端不能把 `room_id` 转为数字 `roomId`。
- 当前 token 返回 `role=audience`；上麦成功后由客户端切 `anchor` 并确认发流。
- token 过期时重新调用该接口，不使用 refresh token。

Client SDK action:

```text
Tencent RTC SDK enterRoom(strRoomId=resp.str_room_id, userId=resp.rtc_user_id, role=audience)
```

### Heartbeat

```http
POST /api/v1/rooms/heartbeat
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_heartbeat_<room_id>_<user_id>_<tick>"
}
```

Rules:

- 只刷新已经存在的业务 presence，不能替代 JoinRoom。
- 用户已经离房、被踢或房间关闭时，客户端应停止心跳并清理本地房间态。
- 心跳间隔由客户端配置控制，但必须小于 room-service 的 presence stale 窗口。

### Leave Room

```http
POST /api/v1/rooms/leave
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_leave_<room_id>_<user_id>_<nonce>"
}
```

Rules:

- 主动关闭房间页、切换账号、被客户端确认退出时调用。
- 如果用户在麦上，LeaveRoom 会释放麦位。
- LeaveRoom 后客户端必须停止 heartbeat、退出 RTC 房、退出或忽略 IM 房间群消息。

## Mic Flow

### Mic Up

```http
POST /api/v1/rooms/mic/up
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_mic_up_<room_id>_<user_id>_<nonce>",
  "seat_no": 1
}
```

Response `data`:

```json
{
  "result": {},
  "seat_no": 1,
  "mic_session_id": "mic_xxx",
  "publish_deadline_ms": 1778000015000,
  "room": {}
}
```

Client actions after success:

1. 保存 `mic_session_id`、`room.version` 和 `publish_deadline_ms`。
2. 确保已有 RTC token；没有或过期则调用 `POST /api/v1/rtc/token`。
3. RTC SDK 切换 `anchor`。
4. RTC SDK 调 `startLocalAudio`。
5. SDK 本地发流成功后调用 `POST /api/v1/rooms/mic/publishing/confirm`。

Rules:

- `MicUp` 成功只代表业务麦位占用成功，不代表 RTC 已经发布音频成功。
- 服务端状态先进入 `pending_publish`。
- 超过 `publish_deadline_ms` 未确认，room-service 会自动 MicDown，reason 为 `publish_timeout`。

### Confirm Mic Publishing

```http
POST /api/v1/rooms/mic/publishing/confirm
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_confirm_publish_<room_id>_<user_id>_<nonce>",
  "target_user_id": 0,
  "mic_session_id": "mic_xxx",
  "room_version": 12,
  "event_time_ms": 1778000001000,
  "source": "client"
}
```

Rules:

- `target_user_id=0` 表示确认当前 actor；RTC webhook 路径才需要显式 target。
- `mic_session_id` 必须等于当前麦位会话。
- `room_version` 和 `event_time_ms` 用于丢弃旧事件，避免旧 audience/leave 事件清理新会话。
- 成功后麦位 `publish_state=publishing`。

### Mic Down

```http
POST /api/v1/rooms/mic/down
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_mic_down_<room_id>_<user_id>_<nonce>",
  "target_user_id": 0,
  "reason": "user_action"
}
```

Rules:

- 普通用户下自己麦时 `target_user_id` 可传 0 或自己 user_id。
- 房管下别人麦时传目标用户 `target_user_id`。
- 客户端收到成功响应或房间系统消息后必须停止本地音频并切回 `audience`。

### Change Mic Seat

```http
POST /api/v1/rooms/mic/change
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_change_mic_<room_id>_<actor_user_id>_<nonce>",
  "target_user_id": 10002,
  "seat_no": 2
}
```

Rules:

- 换麦位只更新业务麦位和 UI，不需要重新进入 RTC。
- 如果 target 当前在发流，客户端继续保持 RTC 上行。

## Room Management APIs

这些接口只允许有权限的 owner/host/admin 调用；gateway 不判断权限，最终由 room-service Room Cell 判断。

| Interface | Body | Result |
| --- | --- | --- |
| `POST /api/v1/rooms/mic/lock` | `room_id, command_id, seat_no, locked` | 锁/解锁麦位 |
| `POST /api/v1/rooms/chat/enabled` | `room_id, command_id, enabled` | 开/关公屏，影响发言守卫 |
| `POST /api/v1/rooms/admin/set` | `room_id, command_id, target_user_id, is_admin` | 设置或取消房管 |
| `POST /api/v1/rooms/host/transfer` | `room_id, command_id, target_user_id` | 转移主持人 |
| `POST /api/v1/rooms/user/mute` | `room_id, command_id, target_user_id, muted, reason` | 禁言或解禁 |
| `POST /api/v1/rooms/user/kick` | `room_id, command_id, target_user_id, reason` | 踢人并 ban，释放 presence 和麦位 |
| `POST /api/v1/rooms/user/unban` | `room_id, command_id, target_user_id, reason` | 解除房间 ban |

Management event handling:

- 管理动作成功后，room-service 写 command log、snapshot 和 outbox。
- 客户端应通过腾讯云 IM 房间系统消息更新 UI。
- 如果本地 UI 状态和系统消息冲突，以最新 room snapshot 和 `room_version` 为准。

## Gift And Interaction

```http
POST /api/v1/rooms/gift/send
Authorization: Bearer <access_token>
Content-Type: application/json
```

Request:

```json
{
  "room_id": "lalu_xxx",
  "command_id": "cmd_send_gift_<room_id>_<user_id>_<nonce>",
  "target_user_id": 10002,
  "gift_id": "rose",
  "gift_count": 1
}
```

Rules:

- `SendGift` 必须先由 wallet-service 扣费成功，再落房间表现。
- 房间表现、热度、本地榜通过 room snapshot 和房间系统消息同步。
- 公屏文本消息不走 gateway HTTP；客户端使用腾讯云 IM 群消息。

## Restore And Reconnect

### Current Room

```http
GET /api/v1/rooms/current
Authorization: Bearer <access_token>
```

Response `data`:

```json
{
  "has_current_room": true,
  "room_id": "lalu_xxx",
  "room_version": 12,
  "role": "audience",
  "mic_session_id": "",
  "publish_state": "",
  "need_join_im_group": true,
  "need_rtc_token": false,
  "server_time_ms": 1778000000000
}
```

Client restore rules:

| Response | Client Action |
| --- | --- |
| `has_current_room=false` | 清理本地房间态，不展示恢复入口 |
| `need_join_im_group=true` | 调 `GET /api/v1/im/usersig`，重新登录 IM 并 join group |
| `need_rtc_token=true` | 调 `POST /api/v1/rtc/token`，重新进入 RTC |
| `publish_state=pending_publish` | 重新执行 SDK 发流并确认当前 `mic_session_id` |
| `publish_state=publishing` | 确认本地 RTC 上行是否仍存在；不确定时重新发流并确认 |

`rooms/current` 是只读恢复探测，不会隐式 JoinRoom，不刷新 heartbeat，也不改变 Room Cell。

### Reconnect Order

1. access token 有效时先调 `GET /api/v1/rooms/current`。
2. 如果 `has_current_room=false`，回房间列表或主界面。
3. 如果 `has_current_room=true`，先恢复 IM，再恢复 RTC。
4. 如果用户原本在麦上，必须使用返回的 `mic_session_id` 继续确认或等待服务端超时下麦。
5. 恢复成功后恢复 `POST /api/v1/rooms/heartbeat` 定时器。

## Server Callback Boundaries

客户端不要直接调用这些接口或内部 RPC：

| Interface | Caller | Purpose |
| --- | --- | --- |
| `POST /api/v1/tencent-im/callback` | Tencent IM | 入群、发言等服务端回调入口 |
| `POST /api/v1/tencent-rtc/callback` | Tencent RTC | RTC 音频事件回调入口 |
| `room-service.VerifyRoomPresence` | gateway / callback | 判断用户是否仍在房间、是否被 ban |
| `room-service.CheckSpeakPermission` | gateway / callback | 判断用户是否允许发公屏 |

客户端只消费这些回调产生的房间系统消息和最新 snapshot，不直接操作内部守卫。

## Error Handling

| Error | Meaning | Client Action |
| --- | --- | --- |
| `UNAUTHORIZED` / `AUTH_REQUIRED` | access token 无效 | refresh 成功后重试；refresh 失败回登录 |
| `PROFILE_REQUIRED` | 资料未完成 | 跳资料补全页，不能进入房间 |
| `NOT_FOUND` | 房间或用户事实不存在 | 清本地目标房间，回列表 |
| `ROOM_CLOSED` | 房间已关闭 | 清房间态，回列表 |
| `PERMISSION_DENIED` | 被踢、被 ban、无权限 | 停止对应操作，按系统消息更新 UI |
| `CONFLICT` | 麦位占用、命令冲突、状态冲突 | 拉最新 snapshot 或等待房间系统消息修正 |
| `UPSTREAM_ERROR` | 内部服务或腾讯云依赖异常 | 保留本地登录态，展示重试 |

不要因为普通网络失败或 5xx 清空登录态。只有 refresh 明确失败、session revoked 或用户主动 logout 才清 token。

## Room Snapshot Sync

当前客户端拿完整房间状态的来源：

- `JoinRoom` 响应里的 room snapshot。
- 房间命令响应里的 room snapshot。
- 腾讯云 IM 房间系统消息。
- `rooms/current` 的恢复摘要。
- `GET /api/v1/rooms/snapshot?room_id=<room_id>` 主动同步接口。

```http
GET /api/v1/rooms/snapshot?room_id=<room_id>
```

该接口只读 Room Cell/snapshot，不刷新 presence，不隐式 JoinRoom，不替代 heartbeat。gateway 使用 access token user_id 作为 viewer，room-service 要求 viewer 仍在该房间；未进房、被踢或被 ban 的用户不能读取完整在线用户和麦位快照。