126 lines
3.0 KiB
Markdown
126 lines
3.0 KiB
Markdown
# 房间关注接口 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`。 |
|