# 房间关注接口 Flutter 对接

## 接口地址

`POST /api/v1/rooms/{room_id}/follow`

`DELETE /api/v1/rooms/{room_id}/follow`

本地开发地址：

```text
http://127.0.0.1:13000
```

## 请求方法

| 方法 | 说明 |
| --- | --- |
| `POST` | 关注房间 |
| `DELETE` | 取消关注房间 |

## 请求头

| Header | 必填 | 模拟值 | 说明 |
| --- | --- | --- | --- |
| `Authorization` | 是 | `Bearer <access_token>` | 登录 access token；服务端从 token 读取当前用户 ID。 |
| `X-App-Code` | 否 | `lalu` | App 编码；登录态接口最终以 token 内的 `app_code` 为准。 |

## 参数

Path 参数：

| 参数 | 必填 | 类型 | 模拟值 | 说明 |
| --- | --- | --- | --- | --- |
| `room_id` | 是 | string | `room_10001` | 房间 ID；只允许字母、数字、下划线、短横线，最长 48 位。 |

Query 参数：无。

请求体：无。不要传 `user_id`，服务端只使用 token 中的当前用户。

关注请求示例：

```http
POST /api/v1/rooms/room_10001/follow
Authorization: Bearer <access_token>
X-App-Code: lalu
```

取消关注请求示例：

```http
DELETE /api/v1/rooms/room_10001/follow
Authorization: Bearer <access_token>
X-App-Code: lalu
```

## 返回体模拟数据

关注成功：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "room_id": "room_10001",
    "is_followed": true,
    "followed_at_ms": 1710000000123,
    "server_time_ms": 1710000000456
  }
}
```

取消关注成功：

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "room_id": "room_10001",
    "is_followed": false,
    "server_time_ms": 1710000000789
  }
}
```

字段说明：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `room_id` | string | 本次操作的房间 ID。 |
| `is_followed` | bool | 当前登录用户是否已关注该房间。 |
| `followed_at_ms` | int64 | 关注成功时间，Unix epoch milliseconds；取消关注返回体不带该字段。 |
| `server_time_ms` | int64 | 服务端当前时间，Unix epoch milliseconds。 |

## 错误处理

失败返回仍使用统一 envelope：

```json
{
  "code": "INVALID_ARGUMENT",
  "message": "invalid argument",
  "request_id": "req_abc"
}
```

| HTTP 状态码 | `code` | 处理方式 |
| --- | --- | --- |
| `400` | `INVALID_ARGUMENT` | `room_id` 为空或格式非法，客户端不要重试，检查传参。 |
| `401` | `UNAUTHORIZED` | token 缺失、无效、过期或会话失效，重新登录。 |
| `403` | `PROFILE_REQUIRED` | 用户资料未完成，跳转资料补全流程。 |
| `404` | `NOT_FOUND` | 关注时房间不存在，刷新房间状态或退出当前房间页。 |
| `409` | `ROOM_CLOSED` | 关注时房间已关闭，刷新房间状态或退出当前房间页。 |
| `502` | `UPSTREAM_ERROR` | 内部服务暂不可用，可提示稍后重试。 |

幂等规则：

| 场景 | 返回 |
| --- | --- |
| 重复关注已关注房间 | `200 OK`，`is_followed=true`，不刷新原 `followed_at_ms`。 |
| 取消未关注房间 | `200 OK`，`is_followed=false`。 |