2026-06-04 18:31:06 +08:00

7.7 KiB

Raw Permalink Blame History

房间锁房 Flutter 对接

地址

本地：

http://127.0.0.1:13000

接口：

方法	地址	说明
`POST`	`/api/v1/rooms/password`	房主设置或清空房间密码
`POST`	`/api/v1/rooms/join`	进入房间；锁房时必须传密码
`GET`	`/api/v1/rooms`	房间列表和搜索，返回 `locked`
`GET`	`/api/v1/rooms/feeds`	Mine 页房间流，返回 `locked`

请求头：

Header	必填	说明
`Authorization`	是	`Bearer <access_token>`
`X-App-Code`	否	App 编码，例如 `lalu`

设置房间密码

POST /api/v1/rooms/password

参数：

字段	必填	类型	说明
`room_id`	是	string	房间 ID
`command_id`	是	string	本次设置动作的幂等键，同一次重试复用
`locked`	是	bool	`true` 设置密码，`false` 清空密码
`password`	`locked=true` 必填	string	房间密码，服务端 trim 后最长 64 字符；`locked=false` 时忽略

请求：

{
  "room_id": "room_10001",
  "command_id": "cmd_room_password_room_10001_1710000000",
  "locked": true,
  "password": "1234"
}

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "result": {
      "applied": true,
      "room_version": 12,
      "server_time_ms": 1710000000456
    },
    "room": {
      "room_id": "room_10001",
      "im_group_id": "room_10001",
      "room_short_id": "100001",
      "title": "Live Room",
      "cover_url": "https://cdn.example/room.png",
      "owner_user_id": "10001",
      "mode": "voice",
      "status": "active",
      "chat_enabled": true,
      "locked": true,
      "heat": 1000,
      "online_count": 12,
      "seat_count": 15,
      "occupied_seat_count": 2,
      "version": 12
    },
    "seats": [],
    "server_time_ms": 1710000000456
  }
}

返回字段：

字段	说明
`data.result.applied`	本次命令是否改变房间状态
`data.result.room_version`	房间最新版本
`data.room.locked`	最新锁房状态
`data.room.version`	房间快照版本
`data.seats`	当前麦位列表

清空房间密码

POST /api/v1/rooms/password

参数：

字段	必填	类型	说明
`room_id`	是	string	房间 ID
`command_id`	是	string	本次清空动作的幂等键
`locked`	是	bool	固定传 `false`

请求：

{
  "room_id": "room_10001",
  "command_id": "cmd_room_unlock_room_10001_1710000100",
  "locked": false
}

返回同设置密码接口，data.room.locked=false。

进入锁房房间

POST /api/v1/rooms/join

参数：

字段	必填	类型	说明
`room_id`	是	string	房间 ID
`command_id`	是	string	本次进房动作的幂等键，同一次重试复用
`role`	否	string	当前传 `audience`
`password`	锁房时必填	string	本次入房密码

请求：

{
  "room_id": "room_10001",
  "command_id": "cmd_join_room_10001_20001_1710000000",
  "role": "audience",
  "password": "1234"
}

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "result": {
      "applied": true,
      "room_version": 13,
      "server_time_ms": 1710000001456
    },
    "room": {
      "room_id": "room_10001",
      "im_group_id": "room_10001",
      "locked": true,
      "version": 13
    },
    "viewer": {
      "user_id": "20001",
      "role": "audience",
      "joined_at_ms": 1710000001456,
      "last_seen_at_ms": 1710000001456
    },
    "im": {
      "group_id": "room_10001",
      "need_join_group": true
    },
    "rtc": {
      "need_token": true,
      "available": true
    },
    "server_time_ms": 1710000001456
  }
}

返回字段：

字段	说明
`data.room.locked`	当前房间是否锁房
`data.viewer.user_id`	当前用户 ID
`data.im.group_id`	JoinRoom 成功后需要加入的腾讯 IM 房间群
`data.im.need_join_group`	`true` 时 Flutter 调腾讯 IM `joinGroup`
`data.rtc.available`	是否拿到 RTC token

进房规则：

场景	结果
未锁房	`password` 可不传
已锁房且密码正确	JoinRoom 成功，再加入 IM 房间群
已锁房且密码错误或缺失	返回 `403 PERMISSION_DENIED`，不要加入 IM 房间群
房主进自己房间	不需要密码
已在房间内重复 JoinRoom	非房主仍要按当前最新密码校验；密码错误返回 `403 PERMISSION_DENIED`

房间列表 locked 字段

GET /api/v1/rooms?tab=hot&query=100001

GET /api/v1/rooms/feeds?tab=followed

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "rooms": [
      {
        "room_id": "room_10001",
        "im_group_id": "room_10001",
        "title": "Live Room",
        "locked": true,
        "online_count": 12,
        "visible_region_id": 1,
        "room_short_id": "100001"
      }
    ],
    "next_cursor": ""
  }
}

字段：

字段	说明
`rooms[].locked`	是否锁房；`true` 时进房前弹密码输入
`rooms[].im_group_id`	房间 IM 群 ID，只能在 JoinRoom 成功后使用
`rooms[].visible_region_id`	房间区域

相关 IM

JoinRoom 成功后加入房间群

接口 POST /api/v1/rooms/join 成功后，Flutter 使用：

data.im.group_id

调用腾讯 IM SDK 加入房间群。

规则：

场景	Flutter 行为
JoinRoom 成功	调腾讯 IM `joinGroup(data.im.group_id)`
JoinRoom 返回 `PERMISSION_DENIED`	不调用 `joinGroup`
JoinRoom 返回 `ROOM_CLOSED` 或 `NOT_FOUND`	不调用 `joinGroup`，刷新列表

房间密码变更区域通知

房主设置或清空密码后，服务端会发区域播报 IM，不再发房间群 IM。

Flutter 需要监听用户所在区域播报群的自定义消息：

{
  "event_id": "room_password_changed:evt_room_xxx",
  "broadcast_type": "room_password_changed",
  "scope": "region",
  "app_code": "lalu",
  "region_id": 1,
  "room_id": "room_10001",
  "actor_user_id": 10001,
  "locked": true,
  "sent_at_ms": 1710000000456,
  "room_version": 12,
  "source_event_id": "evt_room_xxx",
  "action": {
    "type": "refresh_room",
    "room_id": "room_10001"
  }
}

字段：

字段	说明
`broadcast_type`	固定 `room_password_changed`
`scope`	固定 `region`
`region_id`	区域 ID
`room_id`	发生变化的房间
`locked`	最新锁房状态
`room_version`	房间版本；本地只用更大的版本覆盖旧状态
`action.type`	固定 `refresh_room`

处理：

当前页面	行为
房间列表页	更新对应房间卡片 `locked`
房间详情页	如果 `room_id` 相同，刷新房间快照或更新本地 `locked`
密码弹窗打开中	收到同房间更新后，按最新 `locked` 状态决定是否关闭弹窗

房间群系统消息

room_password_changed 不走房间群 IM。房间内用户刷新锁房状态依赖区域播报或接口返回的 room.locked。

错误返回

失败统一返回：

{
  "code": "PERMISSION_DENIED",
  "message": "permission denied",
  "request_id": "req_abc"
}

常见错误：

HTTP	code	说明
`400`	`INVALID_ARGUMENT`	参数缺失、设置密码时密码为空或超过 64 字符
`401`	`UNAUTHORIZED`	token 无效或过期
`403`	`PERMISSION_DENIED`	非房主设置密码、进房密码错误、用户被 ban
`404`	`NOT_FOUND`	房间不存在
`409`	`ROOM_CLOSED`	房间已关闭
`409`	`CONFLICT`	同一个 `command_id` 被不同请求体复用

7.7 KiB Raw Permalink Blame History Unescape Escape