278 lines
8.8 KiB
Markdown
278 lines
8.8 KiB
Markdown
# 房内贡献榜 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 切换或送礼后重拉榜单快照。
|