hyapp-server/docs/flutter对接/房间关注接口Flutter对接.md

房间关注接口 Flutter 对接

接口地址

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

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

本地开发地址：

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 中的当前用户。

关注请求示例：

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

取消关注请求示例：

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

返回体模拟数据

关注成功：

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

取消关注成功：

{
  "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：

{
  "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。