323 lines
11 KiB
Markdown
323 lines
11 KiB
Markdown
# 房间踢人接口 Flutter 对接
|
||
|
||
本文描述 Flutter App 对接房间踢人能力的 HTTP 接口，以及踢人后腾讯 IM 和腾讯 RTC 的客户端处理方式。踢人事实由 `room-service` Room Cell 提交；客户端不能只靠本地 UI 状态判断用户是否仍在房间。
|
||
|
||
## 接口地址
|
||
|
||
`POST /api/v1/rooms/user/kick`
|
||
|
||
`POST /api/v1/rooms/user/unban`
|
||
|
||
本地开发地址：
|
||
|
||
```text
|
||
http://127.0.0.1:13000
|
||
```
|
||
|
||
## 请求方法
|
||
|
||
| 方法 | 接口 | 说明 |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/v1/rooms/user/kick` | 踢出房间用户，并写入房间 ban 集合。 |
|
||
| `POST` | `/api/v1/rooms/user/unban` | 解除房间 ban，允许用户后续重新 JoinRoom。 |
|
||
|
||
## 请求头
|
||
|
||
| Header | 必填 | 模拟值 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `Authorization` | 是 | `Bearer <access_token>` | 登录 access token；服务端从 token 读取当前用户 ID。 |
|
||
| `X-App-Code` | 否 | `lalu` | App 编码；登录态接口最终以 token 内的 `app_code` 为准。 |
|
||
|
||
## 踢出房间用户
|
||
|
||
房主可以踢出房间内用户。当前后端权限矩阵也允许房管管理普通用户；端上如果只开放房主入口，后端仍兼容。
|
||
|
||
请求体：
|
||
|
||
| 字段 | 必填 | 类型 | 模拟值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `room_id` | 是 | string | `room_10001` | 房间 ID。 |
|
||
| `command_id` | 是 | string | `cmd_kick_room_10001_20001_1710000000` | 房间命令幂等键；同一次踢人重试必须复用。 |
|
||
| `target_user_id` | 是 | int64 | `20001` | 被踢用户长 ID。 |
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
POST /api/v1/rooms/user/kick
|
||
Authorization: Bearer <access_token>
|
||
X-App-Code: lalu
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"room_id": "room_10001",
|
||
"command_id": "cmd_kick_room_10001_20001_1710000000",
|
||
"target_user_id": 20001
|
||
}
|
||
```
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_abc",
|
||
"data": {
|
||
"result": {
|
||
"applied": true,
|
||
"room_version": 18,
|
||
"server_time_ms": 1710000000456
|
||
},
|
||
"room": {
|
||
"room_id": "room_10001",
|
||
"status": "active",
|
||
"ban_user_ids": [20001],
|
||
"online_users": [],
|
||
"mic_seats": [],
|
||
"version": 18
|
||
},
|
||
"rtc_kicked": true,
|
||
"rtc_kick_error": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `data.result.applied` | bool | 本次命令是否产生状态变更；重复踢已 ban 且无残留状态的用户可能为 `false`。 |
|
||
| `data.room.ban_user_ids` | int64[] | 当前房间 ban 用户集合；被踢用户会进入该集合。 |
|
||
| `data.room.online_users` | array | 当前业务 presence；被踢用户会被移除。 |
|
||
| `data.room.mic_seats` | array | 如果被踢用户在麦上，对应麦位会被释放。 |
|
||
| `data.rtc_kicked` | bool | 服务端是否已调用 TRTC `RemoveUserByStrRoomId` 移除目标用户。 |
|
||
| `data.rtc_kick_error` | string | TRTC 服务端踢人失败原因；踢人事实已生效，客户端仍按被踢处理。 |
|
||
|
||
## 解除房间 ban
|
||
|
||
解除 ban 只恢复用户后续重新进房资格，不恢复历史 presence、麦位、管理员身份或 RTC 连接。
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
POST /api/v1/rooms/user/unban
|
||
Authorization: Bearer <access_token>
|
||
X-App-Code: lalu
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"room_id": "room_10001",
|
||
"command_id": "cmd_unban_room_10001_20001_1710000100",
|
||
"target_user_id": 20001
|
||
}
|
||
```
|
||
|
||
成功响应字段和踢人一致，`room.ban_user_ids` 中不再包含目标用户。
|
||
|
||
## IM 和 RTC 交互
|
||
|
||
踢人成功后有三层效果，客户端都要按幂等方式处理：
|
||
|
||
| 层 | 服务端行为 | Flutter 处理 |
|
||
| --- | --- | --- |
|
||
| room-service | 移除目标 presence、释放麦位、写入 ban，后续 JoinRoom、RTC token、IM 进群和发言守卫都会拒绝目标用户。 | 被踢用户所有房间接口如果返回 `PERMISSION_DENIED`，立即退出房间页并清理房间态。 |
|
||
| 腾讯 IM 群 | room-service outbox worker 先调用 IM REST 把目标用户移出房间群，再发布 `room_user_kicked` 系统消息给房间内其他用户。 | 普通成员收到 `room_user_kicked` 后刷新在线列表和麦位；被踢用户要监听 IM 群被移除或退群回调作为主要退出信号。 |
|
||
| 腾讯 IM 单聊 | notice-service 监听 `room_outbox.RoomUserKicked`，给被踢用户发送 C2C `room_notice` 私有通知。 | 被踢用户收到 `room_notice` 时执行同一套本地退出逻辑；按 `event_id` 去重，避免和群消息或接口 403 重复弹窗。 |
|
||
| 腾讯 RTC | room-service 在踢人事实提交后尽力调用 TRTC `RemoveUserByStrRoomId`。 | 被踢用户收到 RTC 退房或连接断开回调时调用同一套本地退出逻辑；如果先收到 IM 回调，也要主动 `exitRoom`。 |
|
||
|
||
客户端退出房间的本地动作必须可重复调用：
|
||
|
||
1. 停止本地音频上行。
|
||
2. 调用 TRTC `exitRoom`。
|
||
3. 退出或清理当前房间 IM 群会话。
|
||
4. 停止房间 heartbeat。
|
||
5. 清空当前房间页状态，回到房间列表或 Mine 页面。
|
||
6. 弹出被踢提示。
|
||
|
||
被踢用户不一定能收到房间群里的 `room_user_kicked` 自定义消息，因为服务端会优先把他移出 IM 群。端上必须同时处理 notice-service 的 C2C `room_notice`、IM SDK 的群移除回调、RTC 退房回调和后续接口 403。
|
||
|
||
## IM 自定义消息
|
||
|
||
房间内其他用户会收到群 `TIMCustomElem`，核心字段如下：
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_abc",
|
||
"room_id": "room_10001",
|
||
"event_type": "room_user_kicked",
|
||
"actor_user_id": 10001,
|
||
"target_user_id": 20001,
|
||
"room_version": 18,
|
||
"attributes": {}
|
||
}
|
||
```
|
||
|
||
处理规则：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `event_type` | 固定 `room_user_kicked`。 |
|
||
| `actor_user_id` | 操作者用户 ID；系统驱逐时可能为 `0`。 |
|
||
| `target_user_id` | 被踢用户 ID。 |
|
||
| `room_version` | 房间版本；本地已有更高版本时丢弃旧消息。 |
|
||
|
||
如果 `target_user_id` 是当前登录用户，直接执行本地退出房间动作；如果不是当前用户，只刷新在线列表、麦位和管理面 UI。
|
||
|
||
被踢用户会收到 notice-service 发送的 C2C `TIMCustomElem`，`Ext=room_notice`，核心字段如下：
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_abc",
|
||
"event_type": "room_user_kicked",
|
||
"source_event_type": "RoomUserKicked",
|
||
"app_code": "lalu",
|
||
"room_id": "room_10001",
|
||
"room_version": 18,
|
||
"actor_user_id": 10001,
|
||
"target_user_id": 20001,
|
||
"occurred_at_ms": 1710000000456,
|
||
"source_created_at_ms": 1710000000456
|
||
}
|
||
```
|
||
|
||
C2C 通知和房间群消息使用同一个 `event_id`。Flutter 侧把 `room_user_kicked`、IM 群移除、RTC 退房和接口 403 都归一到同一个 `handleKickedFromRoom(roomId, eventId)` 流程；同一个 `event_id` 或同一个房间的短时间重复退出信号只处理一次。
|
||
|
||
## 错误处理
|
||
|
||
失败返回仍使用统一 envelope：
|
||
|
||
```json
|
||
{
|
||
"code": "PERMISSION_DENIED",
|
||
"message": "permission denied",
|
||
"request_id": "req_abc"
|
||
}
|
||
```
|
||
|
||
| HTTP 状态码 | `code` | 典型场景 | 处理方式 |
|
||
| --- | --- | --- | --- |
|
||
| `400` | `INVALID_ARGUMENT` | `room_id`、`command_id` 或 `target_user_id` 缺失；操作者踢自己。 | 客户端修正参数，不自动重试。 |
|
||
| `401` | `UNAUTHORIZED` | token 缺失、无效、过期或会话失效。 | 重新登录。 |
|
||
| `403` | `PROFILE_REQUIRED` | 用户资料未完成。 | 跳转资料补全流程。 |
|
||
| `403` | `PERMISSION_DENIED` | 非管理角色踢人；房管踢房主；操作者不在房间。 | 隐藏入口或提示无权限。 |
|
||
| `404` | `NOT_FOUND` | 房间不存在。 | 刷新列表或退出房间页。 |
|
||
| `409` | `ROOM_CLOSED` | 房间已关闭。 | 刷新列表或退出房间页。 |
|
||
| `409` | `CONFLICT` | 同一个 `command_id` 被不同请求体复用。 | 为新的用户动作生成新的 `command_id`。 |
|
||
| `502` | `UPSTREAM_ERROR` | 内部服务暂不可用。 | 可提示稍后重试。 |
|
||
|
||
幂等规则：
|
||
|
||
| 场景 | 返回 |
|
||
| --- | --- |
|
||
| 同一个 `command_id` 重试同一次踢人 | 返回同一命令结果，不重复变更房间。 |
|
||
| 同一个 `command_id` 换另一个 `target_user_id` | `409 CONFLICT`。 |
|
||
| 重复踢已 ban 且无残留状态的用户 | `200 OK`，`applied=false`。 |
|
||
| 解封未 ban 用户 | `200 OK`，`applied=false`。 |
|
||
|
||
## Flutter 解析示例
|
||
|
||
```dart
|
||
class RoomCommandResult {
|
||
RoomCommandResult({
|
||
required this.applied,
|
||
required this.roomVersion,
|
||
required this.serverTimeMs,
|
||
});
|
||
|
||
final bool applied;
|
||
final int roomVersion;
|
||
final int serverTimeMs;
|
||
|
||
factory RoomCommandResult.fromJson(Map<String, dynamic> json) {
|
||
return RoomCommandResult(
|
||
applied: json['applied'] as bool? ?? false,
|
||
roomVersion: (json['room_version'] as num?)?.toInt() ?? 0,
|
||
serverTimeMs: (json['server_time_ms'] as num?)?.toInt() ?? 0,
|
||
);
|
||
}
|
||
}
|
||
|
||
class KickUserResult {
|
||
KickUserResult({
|
||
required this.result,
|
||
required this.rtcKicked,
|
||
required this.rtcKickError,
|
||
required this.banUserIds,
|
||
});
|
||
|
||
final RoomCommandResult result;
|
||
final bool rtcKicked;
|
||
final String rtcKickError;
|
||
final List<int> banUserIds;
|
||
|
||
factory KickUserResult.fromJson(Map<String, dynamic> json) {
|
||
final room = json['room'] as Map<String, dynamic>? ?? const {};
|
||
return KickUserResult(
|
||
result: RoomCommandResult.fromJson(
|
||
json['result'] as Map<String, dynamic>? ?? const {},
|
||
),
|
||
rtcKicked: json['rtc_kicked'] as bool? ?? false,
|
||
rtcKickError: json['rtc_kick_error'] as String? ?? '',
|
||
banUserIds: (room['ban_user_ids'] as List<dynamic>? ?? const [])
|
||
.map((value) => (value as num).toInt())
|
||
.toList(),
|
||
);
|
||
}
|
||
}
|
||
|
||
class RoomKickedEvent {
|
||
RoomKickedEvent({
|
||
required this.roomId,
|
||
required this.actorUserId,
|
||
required this.targetUserId,
|
||
required this.roomVersion,
|
||
});
|
||
|
||
final String roomId;
|
||
final int actorUserId;
|
||
final int targetUserId;
|
||
final int roomVersion;
|
||
|
||
bool isSelf(int currentUserId) => targetUserId == currentUserId;
|
||
|
||
factory RoomKickedEvent.fromJson(Map<String, dynamic> json) {
|
||
return RoomKickedEvent(
|
||
roomId: json['room_id'] as String? ?? '',
|
||
actorUserId: (json['actor_user_id'] as num?)?.toInt() ?? 0,
|
||
targetUserId: (json['target_user_id'] as num?)?.toInt() ?? 0,
|
||
roomVersion: (json['room_version'] as num?)?.toInt() ?? 0,
|
||
);
|
||
}
|
||
}
|
||
|
||
class RoomKickNotice {
|
||
RoomKickNotice({
|
||
required this.eventId,
|
||
required this.roomId,
|
||
required this.actorUserId,
|
||
required this.targetUserId,
|
||
required this.roomVersion,
|
||
});
|
||
|
||
final String eventId;
|
||
final String roomId;
|
||
final int actorUserId;
|
||
final int targetUserId;
|
||
final int roomVersion;
|
||
|
||
factory RoomKickNotice.fromJson(Map<String, dynamic> json) {
|
||
return RoomKickNotice(
|
||
eventId: json['event_id'] as String? ?? '',
|
||
roomId: json['room_id'] as String? ?? '',
|
||
actorUserId: (json['actor_user_id'] as num?)?.toInt() ?? 0,
|
||
targetUserId: (json['target_user_id'] as num?)?.toInt() ?? 0,
|
||
roomVersion: (json['room_version'] as num?)?.toInt() ?? 0,
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
调用 HTTP 接口时先解析外层 envelope：只有 `code == "OK"` 时读取 `data`；其他 `code` 按登录态、参数错误、权限错误或服务错误处理，并把 `request_id` 写入客户端日志。
|
||
|
||
客户端生成 `command_id` 时按一次用户动作生成一次，同一次 HTTP 重试复用原 `command_id`；用户再次点击踢人时生成新的 `command_id`。
|