房间贡献md

2026-07-06 12:53:36 +08:00 · 2026-07-06 12:53:36 +08:00 · 7515233227
commit 7515233227
parent 5a03a3d49a
1 changed files with 277 additions and 0 deletions
--- a/docs/flutter对接/房内贡献榜Flutter对接.md
+++ b/docs/flutter对接/房内贡献榜Flutter对接.md
@ -0,0 +1,277 @@
+# 房内贡献榜 Flutter 对接
+
+本文描述语音房内 day/week/month 三个 tab 的贡献榜接口。客户端按当前 tab 独立请求，不再从进房、心跳或送礼接口里复用同一份榜单数据。
+
+## 接口地址
+
+本地开发地址：
+
+```text
+http://127.0.0.1:13000
+```
+
+```http
+GET /api/v1/rooms/{room_id}/contribution-rank?period=day&limit=20
+Authorization: Bearer <access_token>
+X-App-Code: lalu
+```
+
+说明：
+
+| 项 | 说明 |
+| --- | --- |
+| 鉴权 | 必须登录。gateway 使用 token 里的 `user_id` 作为 viewer。 |
+| 房间校验 | viewer 必须仍在当前房间内；不在房间时返回 403。 |
+| 响应外壳 | 统一使用 `{code,message,request_id,data}`。 |
+| 时间单位 | 所有 `*_ms` 都是 Unix epoch milliseconds，统计窗口按 UTC 计算。 |
+
+## 参数
+
+Path 参数：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `room_id` | string | 是 | 房间 ID。只支持字母、数字、下划线和中横线，最长 48 位。 |
+
+Query 参数：
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| `period` | string | 否 | `day` | 榜单周期。可选值：`day`、`week`、`month`。 |
+| `limit` | int32 | 否 | `20` | 返回条数。必须大于 0；服务端最大返回 `100`。 |
+
+周期含义：
+
+| `period` | 统计窗口 |
+| --- | --- |
+| `day` | UTC 当日 00:00:00 到次日 00:00:00，区间为 `[start_at_ms, end_at_ms)`。 |
+| `week` | UTC 自然周，周一 00:00:00 到下周一 00:00:00，区间为 `[start_at_ms, end_at_ms)`。 |
+| `month` | UTC 自然月，1 日 00:00:00 到下月 1 日 00:00:00，区间为 `[start_at_ms, end_at_ms)`。 |
+
+请求示例：
+
+```http
+GET /api/v1/rooms/room_123/contribution-rank?period=week&limit=20
+Authorization: Bearer <access_token>
+X-App-Code: lalu
+```
+
+## 返回值
+
+统一外壳：
+
+```json
+{
+  "code": "OK",
+  "message": "ok",
+  "request_id": "req_xxx",
+  "data": {}
+}
+```
+
+成功返回示例：
+
+```json
+{
+  "code": "OK",
+  "message": "ok",
+  "request_id": "req_room_rank",
+  "data": {
+    "room_id": "room_123",
+    "period": "week",
+    "start_at_ms": 1780329600000,
+    "end_at_ms": 1780934400000,
+    "total": 2,
+    "contribution_rank": [
+      {
+        "rank": 1,
+        "user_id": "43",
+        "score": 900,
+        "gift_value": 900,
+        "updated_at_ms": 1780400001000,
+        "profile": {
+          "user_id": "43",
+          "username": "Luna",
+          "avatar": "https://cdn.example/avatar/43.png",
+          "display_user_id": "10043",
+          "pretty_id": "888888",
+          "pretty_display_user_id": "888888",
+          "gender": "female",
+          "age": 22,
+          "country": "US",
+          "country_name": "United States",
+          "country_display_name": "United States",
+          "country_flag": "https://cdn.example/flags/us.png",
+          "vip": {},
+          "level": {},
+          "level_badges": {},
+          "badges": [],
+          "avatar_frame": {},
+          "profile_card": {},
+          "vehicle": {},
+          "mic_seat_animation": {},
+          "charm": 0
+        }
+      },
+      {
+        "rank": 2,
+        "user_id": "44",
+        "score": 520,
+        "gift_value": 520,
+        "updated_at_ms": 1780390001000,
+        "profile": {
+          "user_id": "44",
+          "username": "Mia",
+          "avatar": "https://cdn.example/avatar/44.png",
+          "display_user_id": "10044",
+          "gender": "",
+          "age": 0,
+          "country": "",
+          "country_name": "",
+          "country_display_name": "",
+          "country_flag": "",
+          "vip": {},
+          "level": {},
+          "level_badges": {},
+          "badges": [],
+          "avatar_frame": {},
+          "profile_card": {},
+          "vehicle": {},
+          "mic_seat_animation": {},
+          "charm": 0
+        }
+      }
+    ],
+    "profiles": [
+      {
+        "user_id": "43",
+        "username": "Luna",
+        "avatar": "https://cdn.example/avatar/43.png",
+        "display_user_id": "10043",
+        "gender": "female",
+        "age": 22,
+        "country": "US",
+        "country_name": "United States",
+        "country_display_name": "United States",
+        "country_flag": "https://cdn.example/flags/us.png",
+        "vip": {},
+        "level": {},
+        "level_badges": {},
+        "badges": [],
+        "avatar_frame": {},
+        "profile_card": {},
+        "vehicle": {},
+        "mic_seat_animation": {},
+        "charm": 0
+      },
+      {
+        "user_id": "44",
+        "username": "Mia",
+        "avatar": "https://cdn.example/avatar/44.png",
+        "display_user_id": "10044",
+        "gender": "",
+        "age": 0,
+        "country": "",
+        "country_name": "",
+        "country_display_name": "",
+        "country_flag": "",
+        "vip": {},
+        "level": {},
+        "level_badges": {},
+        "badges": [],
+        "avatar_frame": {},
+        "profile_card": {},
+        "vehicle": {},
+        "mic_seat_animation": {},
+        "charm": 0
+      }
+    ],
+    "server_time_ms": 1780400005000
+  }
+}
+```
+
+`data` 字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `room_id` | string | 房间 ID。 |
+| `period` | string | 服务端归一化后的周期：`day`、`week`、`month`。 |
+| `start_at_ms` | int64 | 本次榜单统计窗口开始时间，UTC。 |
+| `end_at_ms` | int64 | 本次榜单统计窗口结束时间，UTC。 |
+| `total` | int64 | 当前房间、当前周期内有贡献的总用户数。 |
+| `contribution_rank` | array | 当前页榜单项。空数组表示当前周期暂无贡献数据。 |
+| `profiles` | array | 榜单用户的展示资料列表，顺序和 `contribution_rank` 一致。 |
+| `server_time_ms` | int64 | 服务端当前时间，可用于展示更新时间。 |
+
+`contribution_rank[]` 字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `rank` | int64 | 排名，从 1 开始。 |
+| `user_id` | string | 上榜用户 ID，HTTP JSON 固定按字符串解析。 |
+| `score` | int64 | 榜单分值；当前等于 `gift_value`。 |
+| `gift_value` | int64 | 统计窗口内该用户在本房间送礼贡献总值。 |
+| `updated_at_ms` | int64 | 该用户本周期贡献记录更新时间。 |
+| `profile` | object? | 当前用户展示资料。资料服务异常或用户资料缺失时可能为空。 |
+
+`profile` / `profiles[]` 字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `user_id` | string | 用户长 ID。 |
+| `username` | string | 昵称。 |
+| `avatar` | string | 头像 URL。 |
+| `display_user_id` | string | 展示 ID。 |
+| `pretty_id` | string | 靓号 ID；没有时为空或不返回。 |
+| `pretty_display_user_id` | string | 靓号展示 ID；没有时为空或不返回。 |
+| `gender` | string | 性别展示值。 |
+| `age` | int32 | 年龄。 |
+| `country` | string | 国家码。 |
+| `country_name` | string | 国家名称。 |
+| `country_display_name` | string | 国家展示名。 |
+| `country_flag` | string | 国家旗帜。 |
+| `vip` | object | VIP 展示资料。 |
+| `level` | object | 等级展示资料。 |
+| `level_badges` | object | 等级徽章资料。 |
+| `badges` | array | 当前佩戴徽章。 |
+| `avatar_frame` | object | 当前佩戴头像框。 |
+| `profile_card` | object | 当前佩戴资料卡。 |
+| `vehicle` | object | 当前佩戴座驾。 |
+| `mic_seat_animation` | object | 当前佩戴麦位动画。 |
+| `charm` | int64 | 魅力值。 |
+
+## 错误码
+
+| HTTP | `code` | 场景 |
+| --- | --- | --- |
+| 400 | `INVALID_ARGUMENT` | `room_id` 格式错误、`period` 不是 `day/week/month`、`limit<=0` 或不是数字。 |
+| 401 | `UNAUTHORIZED` | 未登录或 token 无效。 |
+| 403 | `PROFILE_REQUIRED` | 登录用户未完成资料流程，gateway profile gate 拦截。 |
+| 403 | `PERMISSION_DENIED` | viewer 当前不在该房间，不能读取房内贡献榜。 |
+| 502 | `UPSTREAM_ERROR` | room-service 或 user-service 调用失败。 |
+
+失败返回示例：
+
+```json
+{
+  "code": "INVALID_ARGUMENT",
+  "message": "invalid argument",
+  "request_id": "req_bad_period"
+}
+```
+
+## Flutter 调用规则
+
+| 场景 | 处理 |
+| --- | --- |
+| 进入房间后首次展示 | `POST /api/v1/rooms/join` 成功、房间页建立后，请求当前默认 tab，例如 `period=day`。 |
+| tab 切换 | 按 `room_id + period` 单独请求本接口；不要把 day 的数据复制给 week/month。 |
+| 送礼成功后 | 刷新当前展示的 `period`，或收到本地送礼成功事件后延迟刷新；不要依赖送礼接口返回榜单。 |
+| 心跳 | `POST /api/v1/rooms/heartbeat` 只维护在线状态，不用它刷新榜单。 |
+| 进房首包 | 新版进房继续传 `response_mode=lite`；贡献榜由本接口独立拉取。 |
+| 空榜 | `contribution_rank=[]`、`profiles=[]`、`total=0` 时展示空状态。 |
+
+## 相关 IM
+
+本接口没有独立 IM 消息。房间内送礼动效、公屏礼物消息仍按现有送礼链路和房间 IM 事件处理；本接口只用于 Flutter 在面板打开、tab 切换或送礼后重拉榜单快照。