hyapp-server/docs/Flutter麦上心跳接口.md

Flutter 麦上心跳接口

地址

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

参数

字段	类型	必填	说明
room_id	string	是	房间 ID。
command_id	string	是	本次心跳命令 ID。同一次请求重试复用同一个值，下一次心跳换新的值。
target_user_id	int64	否	传 0 或不传表示当前登录用户自己。
mic_session_id	string	是	当前麦位会话 ID，必须使用上麦返回的 mic_session_id。

请求示例：

{
  "room_id": "lalu_xxx",
  "command_id": "cmd_mic_heartbeat_lalu_xxx_123_001",
  "target_user_id": 0,
  "mic_session_id": "mic_xxx"
}

返回值

{
  "code": "OK",
  "message": "OK",
  "request_id": "req_xxx",
  "data": {
    "result": {
      "applied": true,
      "room_version": 18,
      "server_time_ms": 1778000005000
    },
    "seat_no": 1,
    "mic_heartbeat_at_ms": 1778000005000,
    "room": {
      "room_id": "lalu_xxx",
      "version": 18,
      "mic_seats": [
        {
          "seat_no": 1,
          "user_id": 123,
          "publish_state": "publishing",
          "mic_session_id": "mic_xxx",
          "mic_heartbeat_at_ms": 1778000005000,
          "seat_status": "publishing"
        }
      ]
    }
  }
}

字段	说明
data.seat_no	当前用户所在麦位。
data.mic_heartbeat_at_ms	服务端接受本次麦上心跳的时间，UTC epoch milliseconds。
data.room	刷新后的房间快照。
data.room.mic_seats[].mic_heartbeat_at_ms	麦位最近一次服务端接受心跳的时间。
data.room.mic_seats[].publish_state	publishing 表示当前会话已确认发流，可以继续心跳。
data.room.mic_seats[].seat_status	展示状态，常见值为 publishing、muted、occupied、empty、locked。

相关 IM

IM	是否新增	说明
无	否	麦上心跳不广播独立 IM。
room_mic_publish_confirmed	已有	发流确认成功后进入 publishing，Flutter 收到后可以开始麦上心跳。
room_mic_down	已有	用户下麦、离房、被踢、发流超时或 RTC 停止后释放麦位，Flutter 收到后停止麦上心跳。

Flutter 调用规则

1. POST /api/v1/rooms/mic/up 成功后保存 mic_session_id。
2. RTC 发流成功后调用 POST /api/v1/rooms/mic/publishing/confirm。
3. 确认成功且当前麦位 publish_state=publishing 后，周期调用 POST /api/v1/rooms/mic/heartbeat。
4. pending_publish 状态不能调用麦上心跳开始计时。
5. 返回 mic session mismatch 时，本地保存的是旧 mic_session_id，需要刷新房间详情。
6. 收到 room_mic_down 或接口返回用户不在麦上时，停止本地麦上心跳。