hyapp-server/docs/flutter对接/创建房间与IM入群Flutter对接.md

# 创建房间与 IM 入群 Flutter 对接

本文描述 Flutter App 从创建语音房到加入腾讯云 IM 房间群的调用顺序。当前服务端已改为：`CreateRoom` 返回前同步创建腾讯 IM 群；创建成功后，`data.room.im_group_id` 对应的腾讯 IM 群已经存在。

## 接口地址
涉及接口：

| 方法 | 接口 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/im/usersig` | 获取腾讯 IM SDK 登录票据。 |
| `POST` | `/api/v1/rooms/create` | 创建房间；成功前同步创建腾讯 IM 群。 |
| `POST` | `/api/v1/rooms/join` | 建立 room-service 业务 presence；成功后才调用腾讯 IM `joinGroup`。 |

## 请求头

| Header | 必填 | 示例 | 说明 |
| --- | --- | --- | --- |
| `Authorization` | 是 | `Bearer <access_token>` | 登录 access token；服务端从 token 读取当前用户 ID。 |
| `X-App-Code` | 否 | `lalu` | App 编码；登录态接口最终以 token 内的 `app_code` 为准。 |
| `Content-Type` | POST 必填 | `application/json` | JSON 请求体。 |

## 正确调用顺序

```text
1. App 登录后获取 access_token
2. GET /api/v1/im/usersig
3. 腾讯 IM SDK login(user_id, user_sig)
4. POST /api/v1/rooms/create
5. POST /api/v1/rooms/join
6. 腾讯 IM SDK joinGroup(join_response.data.im.group_id)
7. 成功后进入房间页并启动 heartbeat / RTC
```

关键规则：

| 规则 | 说明 |
| --- | --- |
| `CreateRoom` 成功代表 IM 群已创建 | 服务端同步调用腾讯 IM `create_group`，失败时创建接口直接失败，不落房间。 |
| `CreateRoom` 后不要直接 `joinGroup` | 腾讯 IM 回调守卫依赖 room-service presence；必须先 `JoinRoom`。 |
| `im_group_id` 当前等于 `room_id` | 客户端仍然必须使用接口返回字段，不能硬编码映射规则。 |
| `joinGroup` 成功或“已在群内”都按成功处理 | 页面重进、SDK 重连或重复 join 时可能出现已在群内。 |
| `command_id` 同一次用户动作重试必须复用 | 创建房间和进房分别使用不同 `command_id`。 |

## 获取 IM UserSig

请求：

```http
GET /api/v1/im/usersig
Authorization: Bearer <access_token>
X-App-Code: lalu
```

成功响应：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "sdk_app_id": 20036101,
    "user_id": "10001",
    "user_sig": "xxx",
    "expire_at_ms": 1778007200000
  }
}
```

客户端行为：

- `user_id` 是腾讯 IM identifier，直接传给腾讯 IM SDK。
- `user_sig` 按 `expire_at_ms` 缓存；过期前可以复用。
- `UNAUTHORIZED` 或 `PROFILE_REQUIRED` 时不进入房间流程。

## 创建房间

请求：

```http
POST /api/v1/rooms/create
Authorization: Bearer <access_token>
X-App-Code: lalu
Content-Type: application/json

{
  "command_id": "cmd_create_room_10001_1778000000000",
  "seat_count": 10,
  "mode": "voice",
  "room_name": "Live Room",
  "room_avatar": "https://cdn.example/room.png",
  "room_description": "welcome"
}
```

请求字段：

| 字段 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `command_id` | 是 | string | 创建房间动作幂等键；同一次点击超时重试必须复用。 |
| `seat_count` | 否 | int | 不传或传 `0` 使用后台默认麦位数；正数必须命中后台启用座位数。 |
| `mode` | 是 | string | 当前传 `voice`。 |
| `room_name` | 是 | string | 房间标题，最长 128 个字符。 |
| `room_avatar` | 是 | string | 房间封面 URL；不传或空字符串会返回 `INVALID_ARGUMENT`。 |
| `room_description` | 否 | string | 房间简介，最长 512 个字符。 |

成功响应：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "result": {
      "applied": true,
      "room_version": 1,
      "server_time_ms": 1778000000123
    },
    "room": {
      "room_id": "lalu_abc123",
      "im_group_id": "lalu_abc123",
      "room_short_id": "10001",
      "title": "Live Room",
      "cover_url": "https://cdn.example/room.png",
      "description": "welcome",
      "owner_user_id": "10001",
      "mode": "voice",
      "status": "active",
      "chat_enabled": true,
      "locked": false,
      "heat": 0,
      "online_count": 1,
      "seat_count": 10,
      "occupied_seat_count": 0,
      "visible_region_id": 1001,
      "version": 1
    },
    "seats": [
      {
        "seat_no": 1,
        "locked": false
      }
    ],
    "im": {
      "group_id": "lalu_abc123",
      "need_join_group": true
    },
    "server_time_ms": 1778000000123
  }
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `data.room.room_id` | 房间 ID；后续 JoinRoom、heartbeat、RTC 都使用它。 |
| `data.room.im_group_id` | 腾讯 IM 房间群 ID；创建成功时群已存在。 |
| `data.im.group_id` | 同一个 IM 群 ID；客户端最终以 JoinRoom 响应里的 `data.im.group_id` 入群。 |
| `data.result.applied` | `true` 表示本次创建写入；同一 `command_id` 重试可能为 `false`。 |

创建失败处理：

| code | HTTP | 客户端处理 |
| --- | --- | --- |
| `INVALID_ARGUMENT` | 400 | 检查必填字段、座位数、标题长度。 |
| `UNAUTHORIZED` | 401 | 回登录。 |
| `PROFILE_REQUIRED` | 403 | 引导补全资料。 |
| `CONFLICT` | 409 | 当前用户已经有房间；调用 `/api/v1/rooms/me` 恢复已有房间。 |
| `UPSTREAM_ERROR` | 502 | 可能是腾讯 IM 建群失败或 room-service 不可用；不要进入房间页，可提示稍后重试。 |

## JoinRoom 后加入 IM 群

创建房间成功后，房主仍然要调用 `JoinRoom`。原因是 IM 入群回调会检查 room-service presence；只创建房间不能替代进房动作。

请求：

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

{
  "room_id": "lalu_abc123",
  "command_id": "cmd_join_room_lalu_abc123_10001_1778000001000",
  "role": "audience"
}
```

成功响应只展示 IM 相关字段：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_def",
  "data": {
    "room": {
      "room_id": "lalu_abc123",
      "im_group_id": "lalu_abc123",
      "version": 2
    },
    "viewer": {
      "user_id": "10001",
      "role": "owner",
      "joined_at_ms": 1778000001000,
      "last_seen_at_ms": 1778000001000
    },
    "im": {
      "group_id": "lalu_abc123",
      "need_join_group": true
    },
    "rtc": {
      "need_token": true,
      "available": true
    },
    "server_time_ms": 1778000001000
  }
}
```

客户端行为：

| 条件 | 行为 |
| --- | --- |
| `data.im.need_join_group=true` | 调腾讯 IM SDK `joinGroup(data.im.group_id)`。 |
| `joinGroup` 成功 | 开始监听房间群 `TIMCustomElem`，继续 RTC 进房。 |
| `joinGroup` 返回已在群内 | 按成功处理。 |
| `joinGroup` 返回群不存在 | 视为异常；当前服务端 CreateRoom 已同步建群，记录 `request_id` 和 `group_id` 上报。 |
| `joinGroup` 返回被拒绝/无权限 | 重新调用 `JoinRoom`；仍失败则退出房间页。 |

## Flutter 示例

下面示例只展示调用边界，项目内可替换为现有 Dio 封装、错误码枚举和腾讯 IM SDK 适配层。

```dart
class VoiceRoomApi {
  VoiceRoomApi(this._dio);

  final Dio _dio;

  Future<TencentIMUserSig> fetchIMUserSig() async {
    final resp = await _dio.get('/api/v1/im/usersig');
    final data = resp.data['data'] as Map<String, dynamic>;
    return TencentIMUserSig.fromJson(data);
  }

  Future<CreateRoomResult> createRoom({
    required String commandId,
    required String roomName,
    String mode = 'voice',
    int seatCount = 0,
    String roomAvatar = '',
    String roomDescription = '',
  }) async {
    final resp = await _dio.post(
      '/api/v1/rooms/create',
      data: {
        'command_id': commandId,
        'seat_count': seatCount,
        'mode': mode,
        'room_name': roomName,
        'room_avatar': roomAvatar,
        'room_description': roomDescription,
      },
    );
    return CreateRoomResult.fromJson(resp.data['data'] as Map<String, dynamic>);
  }

  Future<JoinRoomResult> joinRoom({
    required String roomId,
    required String commandId,
    String role = 'audience',
    String password = '',
  }) async {
    final resp = await _dio.post(
      '/api/v1/rooms/join',
      data: {
        'room_id': roomId,
        'command_id': commandId,
        'role': role,
        if (password.isNotEmpty) 'password': password,
      },
    );
    return JoinRoomResult.fromJson(resp.data['data'] as Map<String, dynamic>);
  }
}
```

IM 登录和入群：

```dart
class VoiceRoomIMBridge {
  Future<void> ensureLoggedIn(TencentIMUserSig sig) async {
    // 根据项目使用的腾讯云 IM Flutter SDK 版本适配。
    // 常见入参是 sdkAppID、userID、userSig。
    await TencentIMSDK.login(
      sdkAppId: sig.sdkAppId,
      userId: sig.userId,
      userSig: sig.userSig,
    );
  }

  Future<void> joinRoomGroup(String groupId) async {
    try {
      await TencentIMSDK.joinGroup(groupId: groupId);
    } on TencentIMException catch (error) {
      if (_isAlreadyInGroup(error)) {
        return;
      }
      throw error;
    }
  }

  bool _isAlreadyInGroup(TencentIMException error) {
    // 按项目实际 SDK 错误码收敛，例如已在群内、重复入群等。
    return error.code == TencentIMErrors.alreadyInGroup;
  }
}
```

创建并进入自己房间：

```dart
Future<void> createAndEnterRoom({
  required VoiceRoomApi api,
  required VoiceRoomIMBridge im,
  required String roomName,
}) async {
  final sig = await api.fetchIMUserSig();
  await im.ensureLoggedIn(sig);

  final create = await api.createRoom(
    commandId: newCommandId('create_room'),
    roomName: roomName,
  );

  final roomId = create.room.roomId;

  final join = await api.joinRoom(
    roomId: roomId,
    commandId: newCommandId('join_room_$roomId'),
  );

  if (join.im.needJoinGroup) {
    await im.joinRoomGroup(join.im.groupId);
  }

  // join.rtc.available=true 时继续 enterRoom；无论是否进 RTC，业务 presence 已经建立。
  openVoiceRoomPage(join);
}
```

`command_id` 生成建议：

```dart
String newCommandId(String action) {
  final now = DateTime.now().millisecondsSinceEpoch;
  final nonce = randomBase32(8);
  return 'cmd_${action}_${now}_$nonce';
}
```

同一次点击因网络超时重试时，必须复用原 `command_id`；用户重新点击创建或进房时再生成新的 `command_id`。

## 状态机建议

| 状态 | 入口 | 成功下一步 | 失败处理 |
| --- | --- | --- | --- |
| `imLogin` | `/im/usersig` + IM `login` | `createRoom` | 回登录或提示 IM 初始化失败。 |
| `createRoom` | `/rooms/create` | `joinRoom` | 不进入房间页；`CONFLICT` 时查询我的房间。 |
| `joinRoom` | `/rooms/join` | `joinIMGroup` | 不调用 `joinGroup`；展示进房失败。 |
| `joinIMGroup` | IM SDK `joinGroup` | `enterRTC` / 打开房间页 | 已在群内按成功；其他错误退出房间页或重试 JoinRoom。 |
| `inRoom` | 房间页 active | heartbeat loop | heartbeat 失败按重连策略处理。 |

## IM 消息监听

房间系统消息通过腾讯 IM 群 `TIMCustomElem` 下发：

| 字段 | 说明 |
| --- | --- |
| `MsgType` | `TIMCustomElem` |
| `Ext` | `room_system_message` |
| `Data` | JSON 字符串，包含 `event_id`、`room_id`、`event_type`、`room_version` 等。 |
| `CloudCustomData` | 与 `Data` 相同，便于漫游和排障。 |

客户端处理规则：

- 按 `event_id` 去重。
- 按 `room_version` 丢弃旧事件。
- 收到无法解析或版本断层时，调用 `GET /api/v1/rooms/snapshot?room_id={room_id}` 拉最新快照。

## 常见错误处理

| 场景 | 客户端动作 |
| --- | --- |
| `/rooms/create` 返回 `UPSTREAM_ERROR` | 不调用 JoinRoom，不进入房间页；提示稍后重试。 |
| `/rooms/create` 返回 `CONFLICT` | 用户已有房间，调用 `/api/v1/rooms/me` 恢复。 |
| `/rooms/join` 返回 `PERMISSION_DENIED` | 可能被 ban 或锁房密码错误；不调用 `joinGroup`。 |
| IM `joinGroup` 群不存在 | 当前不应出现；记录 `request_id`、`room_id`、`group_id` 上报。 |
| IM 登录票据过期 | 重新调用 `/api/v1/im/usersig` 并 `login`。 |