# Flutter 麦上心跳接口

## 地址

```http
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`。 |

请求示例：

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

## 返回值

```json
{
  "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` 或接口返回用户不在麦上时，停止本地麦上心跳。