1486 lines
57 KiB
Markdown
1486 lines
57 KiB
Markdown
# Fami VIP 五阶段 Flutter 接口对接
|
||
|
||
本文是本次五阶段后端补齐后的 Flutter 执行契约，覆盖 VIP 素材、资源佩戴、房间背景、房间装扮、主页隐私、房间图片消息和腾讯云 IM。字段以 gateway 当前 HTTP DTO 与 room-service 当前 IM 映射为准。
|
||
|
||
## 1. 适用边界
|
||
|
||
- Fami 当前 VIP 体系是 `tiered_privilege_v1`。资格只能读取服务端返回的 `state.effective_benefits`，执行写操作时仍由后端实时复验。
|
||
- Lalu 当前保持 `legacy_timed`。旧版房间背景 `image_url` 请求和不带资源佩戴 `command_id` 的客户端仍兼容；新 Flutter 应统一使用本文新协议。
|
||
- Flutter 不按 VIP 等级、`benefit_code` 或 `resource_code` 拼接素材 URL。只有接口实际返回的 `benefits[].resource`、背包 `resource` 或房间最终快照可以渲染。
|
||
- 用户级装扮与房间级装扮分开：`mic_seat_animation` 走用户资源佩戴；`room_border` 和 `room_name_style` 必须走 Room Cell 的房间装扮接口。
|
||
- 房间背景和房间图片只支持 JPEG、PNG、GIF、WebP。首版不支持 APNG、SVG、视频或外部 URL。
|
||
- 房间状态以 HTTP 快照恢复，腾讯云 IM 只负责实时增量。不能把 IM 是否到达当成权益或持久状态事实。
|
||
|
||
五阶段对应关系：
|
||
|
||
| 阶段 | Flutter 可用结果 |
|
||
| --- | --- |
|
||
| 1. 契约与错误 | VIP 套餐内嵌真实 `resource`；资源装备有 `command_id`；`VIP_BENEFIT_REQUIRED` 有结构化 `data` |
|
||
| 2. 资源映射与复验 | `mic_skin -> mic_seat_animation`、`room_border -> room_border`、`colored_room_name -> room_name_style`；写操作复验当前权益和 entitlement |
|
||
| 3. 背景与装扮 | 房间专用上传、完整媒体元数据、背景保存/切换、房间装扮 Room Cell 快照与 IM |
|
||
| 4. 主页隐私 | 目标统计隐藏显式返回；匿名访问在写入时固化，访客列表不泄露真实 ID |
|
||
| 5. 房间图片 | 专用上传、发言与权益门禁、command log、durable outbox、腾讯云 IM 图片事件 |
|
||
|
||
## 2. 通用 HTTP 约定
|
||
|
||
### 2.1 Base URL
|
||
|
||
```text
|
||
线上：https://api.global-interaction.com
|
||
本地：http://127.0.0.1:13000
|
||
```
|
||
|
||
所有下文路径都拼接在同一 gateway Base URL 后。Flutter 从当前环境配置取得 host，不在业务代码写死域名。
|
||
|
||
### 2.2 Headers
|
||
|
||
| Header | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `Authorization: Bearer {access_token}` | 是 | 当前登录用户 token |
|
||
| `Content-Type: application/json` | JSON 写接口 | 请求体为 JSON |
|
||
| `Content-Type: multipart/form-data` | 上传接口 | 包含 `command_id` 和 `file` |
|
||
| `X-App-Code` | 通常否 | 由 App 包和登录态决定；不得在同一 token 下任意切换 Fami/Lalu |
|
||
|
||
客户端不提交 `app_code`、`user_id`、`actor_user_id`、`request_id`。这些值由 gateway 从登录态和请求上下文注入。
|
||
|
||
### 2.3 Envelope
|
||
|
||
成功：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_xxx",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
失败通常省略 `data`；需要客户端执行动作的错误会返回安全结构化 `data`。业务分支只判断 `code`，不要解析 `message`。日志至少记录 path、`code` 和 `request_id`，不能记录 token。
|
||
|
||
### 2.4 `command_id`
|
||
|
||
- 最大 128 字节，建议 UUID v4 或 `功能前缀 + UUID`。
|
||
- 它是业务幂等键，`request_id` 只是链路追踪，不能替代。
|
||
- 同一次用户动作超时、断网或 5xx 重试必须复用同一个 `command_id` 和完全相同的业务 payload。
|
||
- 同键同 payload 返回原结果；同键换 payload 返回 `IDEMPOTENCY_CONFLICT`。
|
||
- 用户重新选择素材、重新点击形成新的业务动作时生成新键。
|
||
|
||
建议动作边界：
|
||
|
||
| 动作 | command_id 使用范围 |
|
||
| --- | --- |
|
||
| 上传并保存一个房间背景 | upload 与 save 共用 A |
|
||
| 把已保存背景设为当前背景 | set 单独使用 B |
|
||
| 应用一个房间装扮 | apply 使用 C |
|
||
| 上传并发送一条房间图片 | upload 与 send 共用 D |
|
||
| 佩戴一个用户资源 | equip 使用 E |
|
||
|
||
## 3. 接口总览
|
||
|
||
| 功能 | Method | Path |
|
||
| --- | --- | --- |
|
||
| 当前 VIP 最终态 | `GET` | `/api/v1/vip/me` |
|
||
| VIP 套餐与真实素材 | `GET` | `/api/v1/vip/packages` |
|
||
| VIP 功能开关 | `GET/PATCH` | `/api/v1/vip/settings` |
|
||
| 查询我的资源 | `GET` | `/api/v1/users/me/resources?resource_type={type}` |
|
||
| 佩戴用户级资源 | `POST` | `/api/v1/users/me/resources/{resource_id}/equip` |
|
||
| 查询我已佩戴外观 | `GET` | `/api/v1/users/me/appearance` |
|
||
| 查询其他用户已佩戴外观 | `GET` | `/api/v1/users/by-id/{user_id}/appearance` |
|
||
| 上传房间背景 | `POST multipart` | `/api/v1/rooms/{room_id}/backgrounds/upload` |
|
||
| 保存房间背景素材 | `POST` | `/api/v1/rooms/backgrounds/save` |
|
||
| 查询房间背景素材 | `GET` | `/api/v1/rooms/{room_id}/backgrounds` |
|
||
| 切换当前背景 | `POST` | `/api/v1/rooms/backgrounds/set` |
|
||
| 应用房间装扮 | `POST` | `/api/v1/rooms/{room_id}/decorations/apply` |
|
||
| 记录主页访问 | `POST` | `/api/v1/users/{user_id}/visit` |
|
||
| 查询访问我的用户 | `GET` | `/api/v1/users/me/visitors?page=1&page_size=20` |
|
||
| 上传房间图片 | `POST multipart` | `/api/v1/rooms/{room_id}/messages/images/upload` |
|
||
| 发送房间图片 | `POST` | `/api/v1/rooms/{room_id}/messages/image` |
|
||
| 断线后恢复房间最终状态 | `GET` | `/api/v1/rooms/{room_id}/detail` |
|
||
|
||
已有 VIP 购买、体验卡、返现和上线通知接口保持不变：
|
||
|
||
```text
|
||
POST /api/v1/vip/purchase
|
||
POST /api/v1/vip/trial-cards/{entitlement_id}/equip
|
||
DELETE /api/v1/vip/trial-cards/equipped
|
||
GET /api/v1/vip/coin-rebates/current
|
||
POST /api/v1/vip/coin-rebates/statuses
|
||
POST /api/v1/vip/coin-rebates/{rebate_id}/claim
|
||
POST /api/v1/vip/online-notice
|
||
```
|
||
|
||
## 4. VIP 套餐、最终态与真实资源
|
||
|
||
### 4.1 套餐接口
|
||
|
||
```http
|
||
GET /api/v1/vip/packages
|
||
Authorization: Bearer {access_token}
|
||
```
|
||
|
||
无 query 和 body 参数。代表响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_packages",
|
||
"data": {
|
||
"current_vip": {
|
||
"level": 5,
|
||
"name": "VIP5",
|
||
"active": true,
|
||
"started_at_ms": 1784000000000,
|
||
"expires_at_ms": 1786592000000,
|
||
"program_type": "tiered_privilege_v1",
|
||
"config_version": 12
|
||
},
|
||
"packages": [
|
||
{
|
||
"level": 5,
|
||
"name": "VIP5",
|
||
"status": "active",
|
||
"price_coin": 5000,
|
||
"duration_ms": 2592000000,
|
||
"reward_resource_group_id": 0,
|
||
"reward_items": [],
|
||
"can_purchase": true,
|
||
"sort_order": 50,
|
||
"recharge_gate_required": false,
|
||
"required_recharge_coin_amount": 0,
|
||
"user_recharge_coin_amount": 0,
|
||
"purchase_locked_reason": "",
|
||
"benefits": [
|
||
{
|
||
"benefit_code": "mic_skin",
|
||
"name": "VIP麦位皮肤",
|
||
"benefit_type": "decoration",
|
||
"unlock_level": 5,
|
||
"status": "active",
|
||
"trial_enabled": true,
|
||
"resource_id": 5105,
|
||
"resource_type": "mic_seat_animation",
|
||
"execution_scope": "room",
|
||
"auto_equip": false,
|
||
"sort_order": 50,
|
||
"metadata_json": "",
|
||
"created_at_ms": 1784000000000,
|
||
"updated_at_ms": 1784000000000,
|
||
"presentation": {
|
||
"description": "VIP麦位动态皮肤",
|
||
"preview_items": [],
|
||
"numeric_reward": null
|
||
},
|
||
"resource": {
|
||
"resource_id": 5105,
|
||
"resource_code": "fami_vip5_mic",
|
||
"resource_type": "mic_seat_animation",
|
||
"name": "VIP5 Mic",
|
||
"status": "active",
|
||
"grantable": false,
|
||
"grant_strategy": "new_entitlement",
|
||
"usage_scopes": ["room_mic"],
|
||
"asset_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"preview_url": "https://cdn.example.com/vip/v5-mic.png",
|
||
"animation_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"format": "svga",
|
||
"metadata_json": "{\"format\":\"svga\"}",
|
||
"sort_order": 50,
|
||
"created_at_ms": 1784000000000,
|
||
"updated_at_ms": 1784000000000
|
||
}
|
||
}
|
||
],
|
||
"config_version": 12
|
||
}
|
||
],
|
||
"program_config": {
|
||
"app_code": "fami",
|
||
"program_type": "tiered_privilege_v1",
|
||
"level_count": 9,
|
||
"same_level_expiry_policy": "extend_remaining",
|
||
"upgrade_expiry_policy": "replace_from_now",
|
||
"downgrade_purchase_policy": "reject",
|
||
"benefit_inheritance_policy": "target_only",
|
||
"grant_mode": "trial_card",
|
||
"trial_card_enabled": true,
|
||
"status": "active",
|
||
"config_version": 12
|
||
},
|
||
"state": {
|
||
"paid_vip": {
|
||
"level": 5,
|
||
"name": "VIP5",
|
||
"active": true,
|
||
"started_at_ms": 1784000000000,
|
||
"expires_at_ms": 1786592000000,
|
||
"program_type": "tiered_privilege_v1",
|
||
"config_version": 12
|
||
},
|
||
"equipped_trial_card": null,
|
||
"effective_vip": {
|
||
"level": 5,
|
||
"name": "VIP5",
|
||
"active": true,
|
||
"started_at_ms": 1784000000000,
|
||
"expires_at_ms": 1786592000000,
|
||
"program_type": "tiered_privilege_v1",
|
||
"config_version": 12
|
||
},
|
||
"effective_source": "paid",
|
||
"effective_benefits": [
|
||
{
|
||
"benefit_code": "mic_skin",
|
||
"name": "VIP麦位皮肤",
|
||
"benefit_type": "decoration",
|
||
"unlock_level": 5,
|
||
"status": "active",
|
||
"trial_enabled": true,
|
||
"resource_id": 5105,
|
||
"resource_type": "mic_seat_animation",
|
||
"execution_scope": "room",
|
||
"auto_equip": false,
|
||
"sort_order": 50,
|
||
"metadata_json": "",
|
||
"created_at_ms": 1784000000000,
|
||
"updated_at_ms": 1784000000000,
|
||
"presentation": {
|
||
"description": "VIP麦位动态皮肤",
|
||
"preview_items": [],
|
||
"numeric_reward": null
|
||
},
|
||
"resource": {
|
||
"resource_id": 5105,
|
||
"resource_code": "fami_vip5_mic",
|
||
"resource_type": "mic_seat_animation",
|
||
"name": "VIP5 Mic",
|
||
"status": "active",
|
||
"grantable": false,
|
||
"grant_strategy": "new_entitlement",
|
||
"usage_scopes": ["room_mic"],
|
||
"asset_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"preview_url": "https://cdn.example.com/vip/v5-mic.png",
|
||
"animation_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"format": "svga",
|
||
"metadata_json": "{\"format\":\"svga\"}",
|
||
"sort_order": 50,
|
||
"created_at_ms": 1784000000000,
|
||
"updated_at_ms": 1784000000000
|
||
}
|
||
}
|
||
],
|
||
"evaluated_at_ms": 1784265600000,
|
||
"program_config": {
|
||
"app_code": "fami",
|
||
"program_type": "tiered_privilege_v1",
|
||
"config_version": 12
|
||
},
|
||
"user_settings": {
|
||
"app_code": "fami",
|
||
"user_id": 10001,
|
||
"room_entry_notice_enabled": true,
|
||
"online_global_notice_enabled": true,
|
||
"hide_profile_data_enabled": true,
|
||
"anonymous_profile_visit_enabled": true,
|
||
"leaderboard_invisible_enabled": true,
|
||
"updated_at_ms": 0
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
`benefits[].resource` 是可选字段，只有同时满足以下条件才出现：
|
||
|
||
1. `resource_id > 0`；
|
||
2. 资源属于当前 App；
|
||
3. 资源 `status=active`；
|
||
4. 资源的 `resource_type` 与 benefit 精确一致。
|
||
|
||
条件不满足时字段会被完全省略，不会返回空对象。Flutter 展示素材入口应使用：
|
||
|
||
```dart
|
||
final canRenderMaterial = benefit.status == 'active' &&
|
||
benefit.resource != null &&
|
||
benefit.resource!.status == 'active' &&
|
||
benefit.resource!.resourceType == benefit.resourceType;
|
||
```
|
||
|
||
后台配置顺序是“先创建同 App 的真实 active resource，再把该 resource 绑定到 benefit”。真实素材不存在时，该 benefit 必须保持 `status=disabled`、`resource_id=0`，响应不返回 `resource`；不能先启用权益再让客户端使用占位素材。
|
||
|
||
`resource.format` 是客户端选择素材渲染器的唯一格式依据。后端优先取 `metadata_json.format`，缺省时兼容取 `metadata_json.animation_format`，并返回小写值；两者都没有时顶层 `format` 字段省略，Flutter 应当作“格式未配置/当前不支持”，不得根据 `asset_url`、`preview_url` 或 `animation_url` 后缀推断。后台创建 `mic_seat_animation` 或 `room_border` 资源时必须在 `metadata_json.format` 中选择 `png/jpeg/webp/gif/svga/pag/mp4` 之一。
|
||
|
||
当前映射：
|
||
|
||
| benefit_code | resource_type | 应用位置 |
|
||
| --- | --- | --- |
|
||
| `mic_skin` | `mic_seat_animation` | 用户资源 equip 后由 appearance/房间资料投影 |
|
||
| `room_border` | `room_border` | 房间 decoration apply |
|
||
| `colored_room_name` | `room_name_style` | 房间 decoration apply，`decoration_type=colored_room_name` |
|
||
|
||
本版本初始数据只有 Fami VIP4–VIP8 的 `mic_skin` 已绑定可核实资源；`room_border`、`colored_room_name` 和 VIP9 mic 素材当前为 disabled/无 `resource`。Flutter 必须隐藏素材操作，等待后台配置真实资源，不能放占位 URL。
|
||
|
||
### 4.2 当前 VIP 状态
|
||
|
||
```http
|
||
GET /api/v1/vip/me
|
||
```
|
||
|
||
返回根层兼容字段、`program_config` 和完整 `state`。授权只看：
|
||
|
||
```text
|
||
data.state.effective_vip
|
||
data.state.effective_benefits
|
||
data.state.user_settings
|
||
```
|
||
|
||
不要使用根层 `data.level` 重新推导权益。登录、切账号、冷启动、回前台、购买/体验卡切换成功以及收到 VIP 状态类 IM 后重新拉取。
|
||
|
||
### 4.3 VIP 设置
|
||
|
||
```http
|
||
GET /api/v1/vip/settings
|
||
PATCH /api/v1/vip/settings
|
||
```
|
||
|
||
PATCH 是局部更新，至少提交一个字段；显式 `false` 不能当成未提交：
|
||
|
||
```json
|
||
{
|
||
"hide_profile_data_enabled": true,
|
||
"anonymous_profile_visit_enabled": true
|
||
}
|
||
```
|
||
|
||
开关只是用户偏好，不能单独授权。执行主页访问、房间行为或上线通知时，后端会把当前有效 benefit 与对应开关合并判定。
|
||
|
||
## 5. 用户资源查询与幂等佩戴
|
||
|
||
### 5.1 查询背包资源
|
||
|
||
```http
|
||
GET /api/v1/users/me/resources?resource_type=mic_seat_animation
|
||
```
|
||
|
||
`resource_type` 可省略。房间装扮可分别查询 `room_border`、`room_name_style`，但不能调用通用 equip；它们必须走第 7 节 Room Cell 接口。
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_resources",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"entitlement_id": "ent_abc",
|
||
"resource_id": 5105,
|
||
"resource": {
|
||
"resource_id": 5105,
|
||
"resource_code": "fami_vip5_mic",
|
||
"resource_type": "mic_seat_animation",
|
||
"name": "VIP5 Mic",
|
||
"status": "active",
|
||
"grantable": false,
|
||
"grant_strategy": "new_entitlement",
|
||
"usage_scopes": ["room_mic"],
|
||
"asset_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"preview_url": "https://cdn.example.com/vip/v5-mic.png",
|
||
"animation_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"format": "svga",
|
||
"metadata_json": "{\"format\":\"svga\"}",
|
||
"sort_order": 50,
|
||
"created_at_ms": 1784000000000,
|
||
"updated_at_ms": 1784000000000
|
||
},
|
||
"status": "active",
|
||
"quantity": 1,
|
||
"remaining_quantity": 1,
|
||
"effective_at_ms": 1784000000000,
|
||
"expires_at_ms": 1786592000000,
|
||
"source_grant_id": "grant_abc",
|
||
"created_at_ms": 1784000000000,
|
||
"updated_at_ms": 1784000000000,
|
||
"equipped": false
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.2 佩戴用户级资源
|
||
|
||
```http
|
||
POST /api/v1/users/me/resources/5105/equip
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"command_id": "equip_550e8400-e29b-41d4-a716-446655440000",
|
||
"entitlement_id": "ent_abc"
|
||
}
|
||
```
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| path `resource_id` | 是 | 目标资源 ID |
|
||
| `command_id` | Fami 是 | 同一佩戴动作重试复用，最大 128 字节 |
|
||
| `entitlement_id` | 否 | 指定背包实例；省略时由服务端选择当前有效实例 |
|
||
|
||
成功 `data` 就是一条完整背包资源对象，与上一节 `items[]` 同构，且 `equipped=true`。
|
||
|
||
服务端在写入前重新检查：entitlement 仍 active、未过期、有剩余数量、资源仍 active，以及 VIP 绑定资源的对应 benefit 仍有效。用户 VIP 到期后，即使历史 entitlement 仍存在，也不能重新佩戴该 VIP 资源。
|
||
|
||
资源装备不会直接给 Flutter 发腾讯云 IM；wallet 只发布内部 `UserResourceChanged`。用户级外观通过后续 `/users/me/appearance`、房间资料投影或重新进房刷新。
|
||
|
||
### 5.3 佩戴后的外观与房间投影
|
||
|
||
当前用户佩戴态：
|
||
|
||
```http
|
||
GET /api/v1/users/me/appearance
|
||
Authorization: Bearer {access_token}
|
||
```
|
||
|
||
查询其他用户的公开外观使用 `GET /api/v1/users/by-id/{user_id}/appearance`。两个接口的 `data.mic_seat_animation` 同构。下例只展开麦位动效相关字段，其他 appearance 字段以 OpenAPI 为准：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_appearance",
|
||
"data": {
|
||
"user_id": "10001",
|
||
"mic_seat_animation": {
|
||
"resource_id": 5105,
|
||
"resource_code": "fami_vip5_mic",
|
||
"resource_type": "mic_seat_animation",
|
||
"name": "VIP5 Mic",
|
||
"asset_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"preview_url": "https://cdn.example.com/vip/v5-mic.png",
|
||
"animation_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"format": "svga",
|
||
"metadata_json": "{\"format\":\"svga\"}",
|
||
"entitlement_id": "ent_abc",
|
||
"expires_at_ms": 1786592000000
|
||
},
|
||
"resources": [
|
||
{
|
||
"resource_id": 5105,
|
||
"resource_code": "fami_vip5_mic",
|
||
"resource_type": "mic_seat_animation",
|
||
"name": "VIP5 Mic",
|
||
"asset_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"preview_url": "https://cdn.example.com/vip/v5-mic.png",
|
||
"animation_url": "https://cdn.example.com/vip/v5-mic.svga",
|
||
"format": "svga",
|
||
"metadata_json": "{\"format\":\"svga\"}",
|
||
"entitlement_id": "ent_abc",
|
||
"expires_at_ms": 1786592000000
|
||
}
|
||
],
|
||
"server_time_ms": 1784265600000
|
||
}
|
||
}
|
||
```
|
||
|
||
没有佩戴时 `mic_seat_animation={}`。已佩戴但后台没有显式格式时，该对象仍存在但 `format` 字段省略，Flutter 不渲染且不从 URL 推断。房间 join/detail 等响应的 `data.profiles[].mic_seat_animation` 与此对象同构，其他用户的麦位效果必须直接使用该快照中的 `format + animation_url/asset_url`。
|
||
|
||
## 6. 房间背景：上传、保存、切换
|
||
|
||
### 6.1 专用上传
|
||
|
||
```http
|
||
POST /api/v1/rooms/{room_id}/backgrounds/upload
|
||
Authorization: Bearer {access_token}
|
||
Content-Type: multipart/form-data
|
||
|
||
command_id={本次上传并保存动作的幂等键}
|
||
file={binary}
|
||
```
|
||
|
||
服务端同时校验本地文件事实、房主身份、房间 active 和 `custom_room_background` 权益，再写对象存储。
|
||
|
||
| 约束 | 房间背景 |
|
||
| --- | --- |
|
||
| 格式 | JPEG、PNG、GIF、WebP；文件签名、multipart MIME、文件扩展名必须一致 |
|
||
| 文件大小 | 最大 12 MiB |
|
||
| 宽高 | `width <= 2160`、`height <= 3840` |
|
||
| 总像素 | 最大 8,294,400 |
|
||
| 动画 | 仅 GIF/WebP；最多 120 帧，时长 `(0, 15000]ms` |
|
||
| 静态图元数据 | `frame_count=1`、`animated=false`、`duration_ms=0` |
|
||
|
||
Flutter multipart 必须给 part 设置正确 MIME，例如 JPEG 使用 `image/jpeg`。不要把所有文件统一发成 `application/octet-stream`。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_bg_upload",
|
||
"data": {
|
||
"purpose": "room_background",
|
||
"room_id": "fami_room_1001",
|
||
"command_id": "bg_550e8400-e29b-41d4-a716-446655440000",
|
||
"room_version": 17,
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": 345678,
|
||
"width": 1080,
|
||
"height": 1920,
|
||
"animated": false,
|
||
"frame_count": 1,
|
||
"duration_ms": 0,
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"status": "active"
|
||
},
|
||
"server_time_ms": 1784265600000
|
||
}
|
||
}
|
||
```
|
||
|
||
`room_version` 是上传授权时看到的版本，不表示背景已保存或切换。Flutter 必须把整个 `media` 原样保留，不能只保存 URL，也不能改 `object_key`、尺寸、哈希或状态。
|
||
|
||
上传超时重试必须复用同一 `command_id` 和同一文件字节；换文件属于新动作，必须生成新 command。若后续 save 使用同一 command 提交不同媒体，返回 409 `IDEMPOTENCY_CONFLICT`。
|
||
|
||
当前后端不生成 poster/thumbnail，HTTP 中空值会省略 `poster_url`、`thumbnail_url`；IM 为保持固定媒体属性会返回这两个 key，当前值为空字符串。Flutter 不得自行拼接缩略图 URL。
|
||
|
||
### 6.2 保存素材
|
||
|
||
```http
|
||
POST /api/v1/rooms/backgrounds/save
|
||
Content-Type: application/json
|
||
```
|
||
|
||
Fami 请求：
|
||
|
||
```json
|
||
{
|
||
"room_id": "fami_room_1001",
|
||
"command_id": "bg_550e8400-e29b-41d4-a716-446655440000",
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": 345678,
|
||
"width": 1080,
|
||
"height": 1920,
|
||
"animated": false,
|
||
"frame_count": 1,
|
||
"duration_ms": 0,
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"status": "active"
|
||
}
|
||
}
|
||
```
|
||
|
||
`image_url` 可省略，gateway 会从 `media.url` 补齐。Lalu 旧请求仍可只传 `room_id + image_url`。历史 Lalu 背景的列表/当前态和 IM 事件可能只有 `image_url` 或 `room_background_url`，没有嵌套 `media` 及其属性；Flutter 需兼容这种缺省，Fami 新链路则以完整 `media` 为准。
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_bg_save",
|
||
"data": {
|
||
"background": {
|
||
"background_id": 101,
|
||
"room_id": "fami_room_1001",
|
||
"image_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"created_by_user_id": "10001",
|
||
"created_at_ms": 1784265600100,
|
||
"updated_at_ms": 1784265600100,
|
||
"command_id": "bg_550e8400-e29b-41d4-a716-446655440000",
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": 345678,
|
||
"width": 1080,
|
||
"height": 1920,
|
||
"animated": false,
|
||
"frame_count": 1,
|
||
"duration_ms": 0,
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"status": "active"
|
||
}
|
||
},
|
||
"server_time_ms": 1784265600100
|
||
}
|
||
}
|
||
```
|
||
|
||
保存只写房间素材列表，不改变 Room Cell，不发 IM。
|
||
|
||
### 6.3 查询素材
|
||
|
||
```http
|
||
GET /api/v1/rooms/fami_room_1001/backgrounds
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_bg_list",
|
||
"data": {
|
||
"backgrounds": [
|
||
{
|
||
"background_id": 101,
|
||
"room_id": "fami_room_1001",
|
||
"image_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"created_by_user_id": "10001",
|
||
"created_at_ms": 1784265600100,
|
||
"updated_at_ms": 1784265600100,
|
||
"command_id": "bg_550e8400-e29b-41d4-a716-446655440000",
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": 345678,
|
||
"width": 1080,
|
||
"height": 1920,
|
||
"animated": false,
|
||
"frame_count": 1,
|
||
"duration_ms": 0,
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"status": "active"
|
||
}
|
||
}
|
||
],
|
||
"selected_background_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"selected_background": {
|
||
"background_id": 101,
|
||
"room_id": "fami_room_1001",
|
||
"image_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"created_by_user_id": "10001",
|
||
"created_at_ms": 1784265600100,
|
||
"updated_at_ms": 1784265600100,
|
||
"command_id": "bg_550e8400-e29b-41d4-a716-446655440000",
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": 345678,
|
||
"width": 1080,
|
||
"height": 1920,
|
||
"animated": false,
|
||
"frame_count": 1,
|
||
"duration_ms": 0,
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"status": "active"
|
||
}
|
||
},
|
||
"server_time_ms": 1784265600200
|
||
}
|
||
}
|
||
```
|
||
|
||
未设置背景时 `selected_background_url` 和 `selected_background` 会省略。
|
||
|
||
### 6.4 切换当前背景
|
||
|
||
```http
|
||
POST /api/v1/rooms/backgrounds/set
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"room_id": "fami_room_1001",
|
||
"command_id": "bg_set_550e8400-e29b-41d4-a716-446655440001",
|
||
"background_id": "101"
|
||
}
|
||
```
|
||
|
||
`background_id` 接受 JSON 数字或数字字符串。代表响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_bg_set",
|
||
"data": {
|
||
"result": {
|
||
"applied": true,
|
||
"room_version": 18,
|
||
"server_time_ms": 1784265600300
|
||
},
|
||
"room": {
|
||
"room_id": "fami_room_1001",
|
||
"im_group_id": "fami_room_1001",
|
||
"title": "Fami Room",
|
||
"background_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"owner_user_id": "10001",
|
||
"status": "active",
|
||
"chat_enabled": true,
|
||
"locked": false,
|
||
"version": 18,
|
||
"active_background": {
|
||
"background_id": 101,
|
||
"room_id": "fami_room_1001",
|
||
"image_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"created_by_user_id": "10001",
|
||
"created_at_ms": 1784265600100,
|
||
"updated_at_ms": 1784265600100,
|
||
"command_id": "bg_550e8400-e29b-41d4-a716-446655440000",
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": 345678,
|
||
"width": 1080,
|
||
"height": 1920,
|
||
"animated": false,
|
||
"frame_count": 1,
|
||
"duration_ms": 0,
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"status": "active"
|
||
}
|
||
}
|
||
},
|
||
"background": {
|
||
"background_id": 101,
|
||
"room_id": "fami_room_1001",
|
||
"image_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"created_by_user_id": "10001",
|
||
"created_at_ms": 1784265600100,
|
||
"updated_at_ms": 1784265600100,
|
||
"command_id": "bg_550e8400-e29b-41d4-a716-446655440000",
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": 345678,
|
||
"width": 1080,
|
||
"height": 1920,
|
||
"animated": false,
|
||
"frame_count": 1,
|
||
"duration_ms": 0,
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||
"status": "active"
|
||
}
|
||
},
|
||
"server_time_ms": 1784265600300
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.5 背景 IM
|
||
|
||
腾讯云原始 `TIMCustomElem`：
|
||
|
||
| 字段 | 精确值 |
|
||
| --- | --- |
|
||
| `Ext` | `room_system_message` |
|
||
| `Desc` | `room_background_changed` |
|
||
| `Data` | 下方 JSON 的 UTF-8 字符串 |
|
||
| `CloudCustomData` | 与 `Data` 完全相同 |
|
||
|
||
`Data` 同时保留 `attributes`，并把所有 attributes 平铺到顶层。媒体属性在 IM 中都是字符串：
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_xxx",
|
||
"room_id": "fami_room_1001",
|
||
"event_type": "room_background_changed",
|
||
"actor_user_id": 10001,
|
||
"room_version": 18,
|
||
"attributes": {
|
||
"background_id": "101",
|
||
"room_background_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": "345678",
|
||
"width": "1080",
|
||
"height": "1920",
|
||
"animated": "false",
|
||
"frame_count": "1",
|
||
"duration_ms": "0",
|
||
"poster_url": "",
|
||
"thumbnail_url": "",
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
||
},
|
||
"background_id": "101",
|
||
"room_background_url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"url": "https://cdn.example.com/room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"object_key": "room-media/fami/backgrounds/10001/fami_room_1001/x.png",
|
||
"content_type": "image/png",
|
||
"format": "png",
|
||
"size_bytes": "345678",
|
||
"width": "1080",
|
||
"height": "1920",
|
||
"animated": "false",
|
||
"frame_count": "1",
|
||
"duration_ms": "0",
|
||
"poster_url": "",
|
||
"thumbnail_url": "",
|
||
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
||
}
|
||
```
|
||
|
||
状态处理：同房间、`event_id` 未处理且 `room_version >= localRoomVersion` 才应用；如果版本跳跃大于 1，先拉 `/rooms/{room_id}/detail`。断线重进始终使用详情中的 `room.active_background` 恢复，不依赖历史 IM。
|
||
|
||
## 7. 房间边框与彩色房名
|
||
|
||
先从背包查询对应资源：
|
||
|
||
```http
|
||
GET /api/v1/users/me/resources?resource_type=room_border
|
||
GET /api/v1/users/me/resources?resource_type=room_name_style
|
||
```
|
||
|
||
然后由房主应用到具体房间：
|
||
|
||
```http
|
||
POST /api/v1/rooms/fami_room_1001/decorations/apply
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"command_id": "room_decor_550e8400-e29b-41d4-a716-446655440002",
|
||
"decoration_type": "colored_room_name",
|
||
"resource_id": "5205",
|
||
"entitlement_id": "ent_room_name_abc"
|
||
}
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `command_id` | 是 | 最大 128 字节，重试复用 |
|
||
| `decoration_type` | 是 | `room_border` 或 `colored_room_name` |
|
||
| `resource_id` | 是 | JSON 数字或数字字符串 |
|
||
| `entitlement_id` | 否 | 建议明确传实例；省略时服务端选择当前有效实例 |
|
||
|
||
`colored_room_name` 的资源目录类型固定为 `room_name_style`。成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_decor_apply",
|
||
"data": {
|
||
"result": {
|
||
"applied": true,
|
||
"room_version": 19,
|
||
"server_time_ms": 1784265600400
|
||
},
|
||
"room": {
|
||
"room_id": "fami_room_1001",
|
||
"im_group_id": "fami_room_1001",
|
||
"title": "Fami Room",
|
||
"owner_user_id": "10001",
|
||
"status": "active",
|
||
"chat_enabled": true,
|
||
"locked": false,
|
||
"version": 19,
|
||
"room_name_style": {
|
||
"resource_id": 5205,
|
||
"resource_code": "fami_vip_room_name_gold",
|
||
"resource_type": "room_name_style",
|
||
"name": "Gold Room Name",
|
||
"asset_url": "https://cdn.example.com/vip/room-name.json",
|
||
"preview_url": "https://cdn.example.com/vip/room-name.png",
|
||
"metadata_json": "{\"text_colors\":[\"#FFD76A\",\"#FF8A00\"],\"stops\":[0,1],\"angle_degrees\":90}",
|
||
"entitlement_id": "ent_room_name_abc",
|
||
"text_colors": ["#FFD76A", "#FF8A00"],
|
||
"stops": [0, 1],
|
||
"angle_degrees": 90,
|
||
"expires_at_ms": 1786592000000
|
||
}
|
||
},
|
||
"decoration_type": "colored_room_name",
|
||
"resource": {
|
||
"resource_id": 5205,
|
||
"resource_code": "fami_vip_room_name_gold",
|
||
"resource_type": "room_name_style",
|
||
"name": "Gold Room Name",
|
||
"asset_url": "https://cdn.example.com/vip/room-name.json",
|
||
"preview_url": "https://cdn.example.com/vip/room-name.png",
|
||
"metadata_json": "{\"text_colors\":[\"#FFD76A\",\"#FF8A00\"],\"stops\":[0,1],\"angle_degrees\":90}",
|
||
"entitlement_id": "ent_room_name_abc",
|
||
"text_colors": ["#FFD76A", "#FF8A00"],
|
||
"stops": [0, 1],
|
||
"angle_degrees": 90,
|
||
"expires_at_ms": 1786592000000
|
||
},
|
||
"server_time_ms": 1784265600400
|
||
}
|
||
}
|
||
```
|
||
|
||
服务端必须同时验证：当前用户是房主、房间 active、VIP benefit 精确绑定同一 `resource_id/resource_type`、entitlement 有效、资源 active。`expires_at_ms` 是 VIP 与 entitlement 到期时间的较早者。
|
||
|
||
彩色房名 `text_colors` 最多 8 个，颜色只接受 `#RRGGBB` 或 `#RRGGBBAA`；`stops` 若提供，数量必须与颜色一致、范围 `[0,1]` 且升序。Flutter 直接渲染响应字段，不再次解析 `metadata_json` 作为权限事实。
|
||
|
||
房间列表、feed、详情和命令响应会直接返回最终 `room_border`、`room_name_style`；字段不存在表示当前无有效装扮。到达 `expires_at_ms` 时客户端立即隐藏，并刷新房间详情。
|
||
|
||
### 7.1 装扮 IM
|
||
|
||
| TIMCustomElem 字段 | 精确值 |
|
||
| --- | --- |
|
||
| `Ext` | `room_system_message` |
|
||
| `Desc` | `room_decoration_changed` |
|
||
| `Data` | 下方 JSON 字符串 |
|
||
| `CloudCustomData` | 与 `Data` 相同 |
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_xxx",
|
||
"room_id": "fami_room_1001",
|
||
"event_type": "room_decoration_changed",
|
||
"actor_user_id": 10001,
|
||
"room_version": 19,
|
||
"attributes": {
|
||
"decoration_type": "colored_room_name",
|
||
"resource_id": "5205",
|
||
"resource_code": "fami_vip_room_name_gold",
|
||
"resource_type": "room_name_style",
|
||
"name": "Gold Room Name",
|
||
"asset_url": "https://cdn.example.com/vip/room-name.json",
|
||
"preview_url": "https://cdn.example.com/vip/room-name.png",
|
||
"animation_url": "",
|
||
"format": "",
|
||
"metadata_json": "{\"text_colors\":[\"#FFD76A\",\"#FF8A00\"],\"stops\":[0,1],\"angle_degrees\":90}",
|
||
"text_colors": "[\"#FFD76A\",\"#FF8A00\"]",
|
||
"stops": "[0,1]",
|
||
"angle_degrees": "90",
|
||
"entitlement_id": "ent_room_name_abc",
|
||
"expires_at_ms": "1786592000000"
|
||
},
|
||
"decoration_type": "colored_room_name",
|
||
"resource_id": "5205",
|
||
"resource_code": "fami_vip_room_name_gold",
|
||
"resource_type": "room_name_style",
|
||
"name": "Gold Room Name",
|
||
"asset_url": "https://cdn.example.com/vip/room-name.json",
|
||
"preview_url": "https://cdn.example.com/vip/room-name.png",
|
||
"animation_url": "",
|
||
"format": "",
|
||
"metadata_json": "{\"text_colors\":[\"#FFD76A\",\"#FF8A00\"],\"stops\":[0,1],\"angle_degrees\":90}",
|
||
"text_colors": "[\"#FFD76A\",\"#FF8A00\"]",
|
||
"stops": "[0,1]",
|
||
"angle_degrees": "90",
|
||
"entitlement_id": "ent_room_name_abc",
|
||
"expires_at_ms": "1786592000000"
|
||
}
|
||
```
|
||
|
||
注意：IM 内 `text_colors` 和 `stops` 是“JSON 数组的字符串”，HTTP 中才是数组。Flutter IM parser 需要再做一次 `jsonDecode`。`room_name_style` 是结构化样式而不是媒体 renderer，HTTP 不返回 `format`，IM 的通用 attributes 中 `format` 为空字符串；客户端直接使用颜色、stops 和角度。
|
||
|
||
当后台禁用/改绑资源、entitlement 撤销、VIP 或等级配置失效时，wallet outbox 会驱动 Room Cell 清除已失效装扮。清除仍使用 `room_decoration_changed`：`decoration_type` 保留原槽位，`resource_id` 固定为字符串 `"0"`，其他资源 attributes 为空值。Flutter 收到后必须立即清空对应的 `room_border` 或 `room_name_style` 槽位，不能尝试查询资源 ID 0。状态事件统一按 `event_id + room_version` 去重和排序；纯自然到期不保证恰好有 IM，仍要按 `expires_at_ms` 本地到点隐藏并拉详情校准。
|
||
|
||
## 8. 主页数据隐藏与匿名访问
|
||
|
||
### 8.1 记录主页访问
|
||
|
||
```http
|
||
POST /api/v1/users/{target_user_id}/visit
|
||
Authorization: Bearer {access_token}
|
||
```
|
||
|
||
无 body。公开响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_visit_public",
|
||
"data": {
|
||
"recorded": true,
|
||
"target_stats_hidden": false,
|
||
"target_stats": {
|
||
"visitors_count": 20,
|
||
"following_count": 8,
|
||
"friends_count": 5,
|
||
"updated_at_ms": 1784265600500
|
||
},
|
||
"target_profile": {
|
||
"user_id": "20002",
|
||
"display_user_id": "888002",
|
||
"username": "Nina",
|
||
"avatar": "https://cdn.example.com/avatar.png"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
目标用户的 `hide_profile_data` 权益和同名开关当前生效时：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_visit_hidden",
|
||
"data": {
|
||
"recorded": true,
|
||
"target_stats_hidden": true,
|
||
"target_profile": {
|
||
"user_id": "20002",
|
||
"display_user_id": "888002",
|
||
"username": "Nina",
|
||
"avatar": "https://cdn.example.com/avatar.png"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
`target_stats_hidden=true` 时 `target_stats` 字段完全不存在，不会返回 `null` 或伪造的 0。Flutter 必须用显式布尔值控制统计区：
|
||
|
||
```dart
|
||
if (data.targetStatsHidden) {
|
||
hideProfileStats();
|
||
} else {
|
||
renderProfileStats(data.targetStats!);
|
||
}
|
||
```
|
||
|
||
`recorded=true` 表示首次形成该公开/匿名聚合项；同一身份重复访问会累计次数并更新时间，可能返回 `recorded=false`，不表示请求失败。
|
||
|
||
匿名与公开身份在“本次写入时”决定：
|
||
|
||
- 访问者当时 `anonymous_profile_visit` 权益和开关都生效，写匿名表并固定随机 `anonymous_visit_id`。
|
||
- 以后关闭开关或 VIP 到期，历史匿名记录仍保持匿名。
|
||
- 同一真实用户先公开访问、后匿名访问，会形成两个独立展示聚合；历史公开记录不会改写，匿名记录也不会借公开记录泄露身份。
|
||
- 匿名权益查询失败时本次访问不落库并返回上游错误；目标统计隐藏查询失败时按隐藏处理，避免泄漏。
|
||
- 当前 App 访问链路不设好友或管理员白名单；除本人访问本身会直接被拒绝外，其他查看者一律以 `target_stats_hidden` 为最终结论。
|
||
|
||
### 8.2 查询我的访客
|
||
|
||
```http
|
||
GET /api/v1/users/me/visitors?page=1&page_size=20
|
||
```
|
||
|
||
`page` 默认为 1，`page_size` 默认为 20，显式传值时两者都必须大于 0，且 `page` 和 `page_size` 都不能超过 100。超限时返回 HTTP 400 + `INVALID_ARGUMENT`，Flutter 应修正本地分页参数，不要当作空页或自动重试。这个边界把公开与匿名两个分支的单次合并窗口固定在最多各 10,000 条。
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_visitors",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"visitor_user_id": "30003",
|
||
"visitor_identity_hidden": false,
|
||
"target_user_id": "20002",
|
||
"visit_count": 4,
|
||
"last_visited_at_ms": 1784265600600
|
||
},
|
||
{
|
||
"anonymous_visit_id": "anon_0123456789abcdef0123456789abcdef",
|
||
"visitor_identity_hidden": true,
|
||
"target_user_id": "20002",
|
||
"visit_count": 2,
|
||
"last_visited_at_ms": 1784265500000
|
||
}
|
||
],
|
||
"total": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
解析规则：
|
||
|
||
| `visitor_identity_hidden` | 必须存在 | 必须不存在 | UI |
|
||
| --- | --- | --- | --- |
|
||
| `false` | `visitor_user_id` | `anonymous_visit_id` | 可按 user_id 拉取公开资料 |
|
||
| `true` | `anonymous_visit_id` | `visitor_user_id` | 展示匿名头像/名称；不能发起资料查询 |
|
||
|
||
`anonymous_visit_id` 是随机、目标用户作用域内稳定的展示 ID；不同被访问者看到的值不同，不能跨用户关联。主页访问和列表不发送 IM。
|
||
|
||
## 9. 房间图片消息
|
||
|
||
### 9.1 专用上传
|
||
|
||
```http
|
||
POST /api/v1/rooms/{room_id}/messages/images/upload
|
||
Authorization: Bearer {access_token}
|
||
Content-Type: multipart/form-data
|
||
|
||
command_id={本次上传并发送动作的幂等键}
|
||
file={binary}
|
||
```
|
||
|
||
上传前服务端校验：房间 active、当前用户仍在房、未被 ban、未被禁言、公屏开启，以及 `room_image_message` 当前生效。用户不要求在麦位上。
|
||
|
||
| 约束 | 房间图片 |
|
||
| --- | --- |
|
||
| 格式 | JPEG、PNG、GIF、WebP；签名、MIME、扩展名一致 |
|
||
| 文件大小 | 最大 8 MiB |
|
||
| 宽高 | `width <= 4096`、`height <= 4096` |
|
||
| 总像素 | 最大 16,777,216 |
|
||
| 动画 | 仅 GIF/WebP；最多 120 帧，最长 15 秒 |
|
||
|
||
成功响应与背景上传同构，但：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_image_upload",
|
||
"data": {
|
||
"purpose": "room_image",
|
||
"room_id": "fami_room_1001",
|
||
"command_id": "room_image_550e8400-e29b-41d4-a716-446655440003",
|
||
"room_version": 19,
|
||
"media": {
|
||
"url": "https://cdn.example.com/room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"object_key": "room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"content_type": "image/webp",
|
||
"format": "webp",
|
||
"size_bytes": 456789,
|
||
"width": 800,
|
||
"height": 800,
|
||
"animated": true,
|
||
"frame_count": 12,
|
||
"duration_ms": 2400,
|
||
"sha256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
|
||
"status": "active"
|
||
},
|
||
"server_time_ms": 1784265600700
|
||
}
|
||
}
|
||
```
|
||
|
||
图片上传超时同样只能用原 `command_id + 同一文件` 重试；重新选图生成新 command。当前 `poster_url/thumbnail_url` 不生成，HTTP 为空时省略，IM 中以空字符串出现。
|
||
|
||
### 9.2 发送图片
|
||
|
||
```http
|
||
POST /api/v1/rooms/fami_room_1001/messages/image
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"command_id": "room_image_550e8400-e29b-41d4-a716-446655440003",
|
||
"image": {
|
||
"url": "https://cdn.example.com/room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"object_key": "room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"content_type": "image/webp",
|
||
"format": "webp",
|
||
"size_bytes": 456789,
|
||
"width": 800,
|
||
"height": 800,
|
||
"animated": true,
|
||
"frame_count": 12,
|
||
"duration_ms": 2400,
|
||
"sha256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
|
||
"status": "active"
|
||
}
|
||
}
|
||
```
|
||
|
||
必须原样使用上传响应的整个 `media`。成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_image_send",
|
||
"data": {
|
||
"result": {
|
||
"applied": true,
|
||
"room_version": 20,
|
||
"server_time_ms": 1784265600800
|
||
},
|
||
"accepted": true,
|
||
"message_id": "room_msg_0123456789abcdef0123456789abcdef",
|
||
"room_id": "fami_room_1001",
|
||
"sender_user_id": "10001",
|
||
"server_time_ms": 1784265600800,
|
||
"image": {
|
||
"url": "https://cdn.example.com/room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"object_key": "room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"content_type": "image/webp",
|
||
"format": "webp",
|
||
"size_bytes": 456789,
|
||
"width": 800,
|
||
"height": 800,
|
||
"animated": true,
|
||
"frame_count": 12,
|
||
"duration_ms": 2400,
|
||
"sha256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
|
||
"status": "active"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
`accepted=true` 表示 command log 与 durable outbox 已提交，不表示腾讯云 IM 已到达每个在线客户端。`message_id` 由 `app_code + room_id + command_id` 稳定生成；相同请求重放仍返回同一个值。
|
||
|
||
服务端对同一 command 只提交一条逻辑图片消息和一条 outbox 事实；补偿投递或 SDK 漫游仍可能让客户端观察到重复到达，所以 Flutter 用 `event_id` 去重，并以 `message_id` 作为跨投递/乐观消息合并兜底。
|
||
|
||
发送者可用 HTTP 响应先插入一条 `sending/pending` UI 消息，收到 IM 后按 `message_id` 合并成已确认状态，不能再插入第二条。
|
||
|
||
### 9.3 图片 IM
|
||
|
||
| TIMCustomElem 字段 | 精确值 |
|
||
| --- | --- |
|
||
| `Ext` | `room_system_message` |
|
||
| `Desc` | `room_image_message` |
|
||
| `Data` | 下方 JSON 字符串 |
|
||
| `CloudCustomData` | 与 `Data` 相同 |
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_xxx",
|
||
"room_id": "fami_room_1001",
|
||
"event_type": "room_image_message",
|
||
"actor_user_id": 10001,
|
||
"room_version": 20,
|
||
"attributes": {
|
||
"message_id": "room_msg_0123456789abcdef0123456789abcdef",
|
||
"command_id": "room_image_550e8400-e29b-41d4-a716-446655440003",
|
||
"sender_user_id": "10001",
|
||
"image_url": "https://cdn.example.com/room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"image_object_key": "room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"image_content_type": "image/webp",
|
||
"image_format": "webp",
|
||
"image_size_bytes": "456789",
|
||
"image_width": "800",
|
||
"image_height": "800",
|
||
"image_animated": "true",
|
||
"image_frame_count": "12",
|
||
"image_duration_ms": "2400",
|
||
"image_poster_url": "",
|
||
"image_thumbnail_url": "",
|
||
"image_sha256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
|
||
},
|
||
"message_id": "room_msg_0123456789abcdef0123456789abcdef",
|
||
"command_id": "room_image_550e8400-e29b-41d4-a716-446655440003",
|
||
"sender_user_id": "10001",
|
||
"image_url": "https://cdn.example.com/room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"image_object_key": "room-media/fami/images/10001/fami_room_1001/y.webp",
|
||
"image_content_type": "image/webp",
|
||
"image_format": "webp",
|
||
"image_size_bytes": "456789",
|
||
"image_width": "800",
|
||
"image_height": "800",
|
||
"image_animated": "true",
|
||
"image_frame_count": "12",
|
||
"image_duration_ms": "2400",
|
||
"image_poster_url": "",
|
||
"image_thumbnail_url": "",
|
||
"image_sha256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
|
||
}
|
||
```
|
||
|
||
所有 `attributes`/平铺媒体值都是字符串。图片消息是内容流，不能因为 `room_version < localRoomVersion` 就丢弃；先按 `event_id` 去除 outbox 重投，再按 `message_id` 合并发送者的乐观消息或 SDK 重复消息。
|
||
|
||
## 10. `VIP_BENEFIT_REQUIRED` 结构化错误
|
||
|
||
资源佩戴、背景上传/保存/切换、房间装扮、房间图片上传/发送和上线通知都会在执行前复验权益。失败统一为：
|
||
|
||
```http
|
||
HTTP/1.1 403 Forbidden
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": "VIP_BENEFIT_REQUIRED",
|
||
"message": "vip benefit is required",
|
||
"request_id": "req_denied",
|
||
"data": {
|
||
"benefit_code": "room_image_message",
|
||
"required_level": 3,
|
||
"current_effective_level": 2,
|
||
"action": "send_room_image"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `benefit_code` | string | 本次缺失的精确权益 |
|
||
| `required_level` | int | 当前 App 首个显式配置该权益的 active 等级；`0` 表示当前未配置 |
|
||
| `current_effective_level` | int | 付费 VIP 与体验卡合并后的当前有效等级 |
|
||
| `action` | string | 被拒绝的后端动作。背景链路依次为 `upload_room_background`、`save_room_background`、`set_room_background`；其他动作包括 `equip_resource`、`apply_room_decoration`、`upload_room_image`、`send_room_image` |
|
||
|
||
Flutter 处理：关闭 loading，保留用户尚未提交的本地选择，刷新 `/api/v1/vip/me` 和必要的 `/api/v1/vip/packages`，显示升级/续费入口。不要只修改本地等级后自动重试。
|
||
|
||
## 11. 其他错误矩阵
|
||
|
||
| HTTP | code | 场景 | Flutter 动作 |
|
||
| --- | --- | --- | --- |
|
||
| 400 | `INVALID_JSON` | JSON 无法解析 | 修正客户端序列化，不重试同一 body |
|
||
| 400 | `INVALID_ARGUMENT` | command、ID 或媒体元数据不完整 | 停止重试，重新构造请求 |
|
||
| 400 | `INVALID_MEDIA_DIMENSIONS` | 宽高、像素、帧数或动画时长越界 | 提示重新选择或在客户端压缩 |
|
||
| 401 | `UNAUTHORIZED` / token 类错误 | 登录态失效 | 走统一刷新 token/登录流程 |
|
||
| 403 | `PROFILE_REQUIRED` | 资料未完成 | 先完成资料 |
|
||
| 403 | `PERMISSION_DENIED` | 非房主、不在房、被 ban/禁言、对象不归属当前用户/房间 | 关闭对应操作并刷新房间状态 |
|
||
| 403 | `VIP_BENEFIT_REQUIRED` | 权益、开关或等级不满足 | 按第 10 节刷新 VIP |
|
||
| 404 | `NOT_FOUND` | 房间、背景、resource 或 entitlement 不存在 | 刷新对应列表 |
|
||
| 409 | `IDEMPOTENCY_CONFLICT` | 同 command_id 换了 payload | 客户端 bug；新动作生成新 ID，旧动作仍用旧 body |
|
||
| 409 | `ROOM_CLOSED` | 房间已关闭 | 退出房间并停止上传/发送 |
|
||
| 409 | `CONFLICT` | 记录匿名访问时的极低概率展示 ID 碰撞；事务已回滚 | 发起一次新的访问请求，让服务端重新生成随机 ID；不得回退为公开记录或在客户端构造匿名 ID |
|
||
| 409 | `CONFLICT` | 公屏关闭或当前状态不允许 | 刷新详情，不自动换 command 重试 |
|
||
| 413 | `FILE_TOO_LARGE` | 背景超过 12MiB、房间图片超过 8MiB | 客户端压缩或重选 |
|
||
| 415 | `UNSUPPORTED_MEDIA_TYPE` | 签名、MIME、扩展名不一致，或 APNG/其他格式 | 转码为受支持格式 |
|
||
| 500 | `INTERNAL_ERROR` | 服务端持久化或未分类内部错误 | 保留 `request_id` 上报；不得在本地伪造访问成功或隐私结论 |
|
||
| 502 | `UPSTREAM_ERROR` | owner service、wallet 或对象存储暂不可用 | 保留当前 command 与 payload，退避重试 |
|
||
| 503 | `UPSTREAM_ERROR` | 上传或房间 VIP 依赖未就绪 | 保留当前 command 与 payload，退避重试 |
|
||
|
||
`FILE_TOO_LARGE`、`UNSUPPORTED_MEDIA_TYPE`、`INVALID_MEDIA_DIMENSIONS` 是上传专用 code。不要把所有失败都显示成“VIP不足”。
|
||
|
||
## 12. 腾讯云 IM 统一路由与去重
|
||
|
||
room-service 调腾讯云 REST 时使用以下原始形态；`CloudCustomData` 是消息级字段，不在 `TIMCustomElem.MsgContent` 内：
|
||
|
||
```json
|
||
{
|
||
"CloudCustomData": "{与 Data 相同的 JSON 字符串}",
|
||
"MsgBody": [
|
||
{
|
||
"MsgType": "TIMCustomElem",
|
||
"MsgContent": {
|
||
"Data": "{业务 JSON 字符串}",
|
||
"Desc": "room_image_message",
|
||
"Ext": "room_system_message",
|
||
"Sound": ""
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Flutter SDK 中通常对应 `customElem.data/desc/extension`；具体 Dart 包字段名可以不同，但字节内容和值不能改写。
|
||
|
||
### 12.1 相关消息表
|
||
|
||
| 场景 | 会话 | Ext | Desc |
|
||
| --- | --- | --- | --- |
|
||
| VIP 激活 | C2C | `vip_notice` | `VipActivated` |
|
||
| VIP 进房展示 | 当前房间群 | `room_system_message` | `room_user_joined` |
|
||
| VIP 上线全服通知 | 全局播报群 | `im_broadcast` | `vip_online_notice` |
|
||
| 房间背景切换 | 当前房间群 | `room_system_message` | `room_background_changed` |
|
||
| 房间装扮切换 | 当前房间群 | `room_system_message` | `room_decoration_changed` |
|
||
| 房间图片 | 当前房间群 | `room_system_message` | `room_image_message` |
|
||
|
||
用户资源 equip 没有客户端 IM。主页隐私写入也没有 IM。
|
||
房间图片和房间装扮的客户端实时入口分别只有 `room_image_message`、`room_decoration_changed` 这两个 custom event；不要再等待 wallet/VIP 的第二条消息确认同一次房间动作。
|
||
|
||
### 12.2 Flutter 路由顺序
|
||
|
||
1. 从 `V2TimMessage.customElem` 读取 `extension/ext`、`desc`、`data`；SDK 字段名因封装不同，值必须与上表完全匹配。
|
||
2. `Ext=room_system_message` 时解析 `Data` JSON。
|
||
3. 验证 `data.event_type == Desc`、`data.room_id == currentRoomId`。
|
||
4. 用进程内有界 LRU/TTL 集合按 `event_id` 去重；建议每个房间保留最近 1000 个或 30 分钟。
|
||
5. 背景/装扮是状态事件：再按 `room_version` 排序，版本断层时拉详情。
|
||
6. 图片是内容事件：按 `message_id` 再去重，不用本地较新的 room version 丢弃旧图片。
|
||
|
||
伪代码：
|
||
|
||
```dart
|
||
void onCustomMessage(CustomElem elem) {
|
||
if (elem.extension != 'room_system_message') return;
|
||
final event = jsonDecode(utf8.decode(elem.data)) as Map<String, dynamic>;
|
||
if (event['event_type'] != elem.desc) return;
|
||
if (event['room_id'] != currentRoomId) return;
|
||
|
||
final eventId = event['event_id'] as String? ?? '';
|
||
if (eventId.isEmpty || handledEventIds.contains(eventId)) return;
|
||
handledEventIds.add(eventId);
|
||
|
||
switch (event['event_type']) {
|
||
case 'room_background_changed':
|
||
applyBackgroundStateEvent(event);
|
||
break;
|
||
case 'room_decoration_changed':
|
||
applyDecorationStateEvent(event);
|
||
break;
|
||
case 'room_image_message':
|
||
mergeRoomImageByMessageId(event);
|
||
break;
|
||
}
|
||
}
|
||
```
|
||
|
||
腾讯云 IM 的 `Data` 和 `CloudCustomData` 内容相同；正常只消费一次 `customElem.data`。不要同时消费两份造成重复。
|
||
|
||
服务端群消息的腾讯 `Random` 已由 `event_id` 稳定派生，可收敛腾讯短窗口内的相同事件重试；超出腾讯去重窗口的 outbox 补偿仍可能再次到达，因此 Flutter 的 `event_id` 去重不可省略，图片再以 `message_id` 合并兜底。
|
||
|
||
### 12.3 刷新与恢复
|
||
|
||
| 时机 | HTTP 刷新 |
|
||
| --- | --- |
|
||
| 登录/切账号/冷启动/回前台 | `/vip/me` |
|
||
| 打开 VIP 中心 | 并发 `/vip/me` + `/vip/packages` |
|
||
| VIP 购买或体验卡成功 | 使用写响应更新；必要时再拉 `/vip/me` 和 `/vip/packages` |
|
||
| 用户资源佩戴成功 | 先用写响应更新背包，再拉 `/users/me/appearance`；已在房内时重拉 `/rooms/{room_id}/detail` 更新 `profiles[].mic_seat_animation` |
|
||
| 进入或重连房间 | `/rooms/{room_id}/detail` 初始化 `active_background`、`room_border`、`room_name_style` |
|
||
| 背景/装扮 IM 版本断层 | `/rooms/{room_id}/detail` |
|
||
| 装扮到 `expires_at_ms` | 本地立即隐藏，再拉详情确认 |
|
||
| 主页打开 | 先资料接口，再 `POST /users/{id}/visit`；按 `target_stats_hidden` 渲染 |
|
||
| 访客页打开/下拉刷新 | `/users/me/visitors` |
|
||
|
||
房间恢复请求为 `GET /api/v1/rooms/{room_id}/detail`；`room_id` 是必填 path 参数，无 query 和 body。成功响应 `data` 字段如下：
|
||
|
||
| 字段 | 含义 |
|
||
| --- | --- |
|
||
| `room` | 房间最终态，含可选 `active_background/room_border/room_name_style` |
|
||
| `viewer` / `permissions` / `is_followed` | 当前用户的房内身份、可操作权限与关注状态 |
|
||
| `seats` / `rank_top` / `online_count` / `profiles` | 麦位、首屏贡献榜、在线数和用户展示资料；`profiles` 可省略 |
|
||
| `im` / `rtc` | 腾讯 IM 群进入参数与 RTC 凭据状态 |
|
||
| `server_time_ms` | UTC Unix epoch milliseconds |
|
||
|
||
不要持久化“拥有某权益”的最终判断。磁盘缓存最多用于首帧占位；所有敏感写操作都必须接受服务端实时拒绝。
|
||
|
||
## 13. Flutter 模块执行方案
|
||
|
||
建议按五个边界落地：
|
||
|
||
1. `VipRepository`
|
||
- 解析 `/vip/me`、`/vip/packages`、资源列表和结构化 VIP 错误。
|
||
- 以 `(appCode, configVersion)` 隔离缓存，不能把 Fami 权益合并到 Lalu。
|
||
2. `AppearanceRepository`
|
||
- 解析当前/公开 appearance 以及房间 `profiles[]`中的同构资源外观。
|
||
- 只根据显式 `format` 选择渲染器；字段缺省就不渲染，不从 URL 后缀推断。
|
||
3. `RoomMediaRepository`
|
||
- 负责 MIME 检测、multipart 上传、保存/发送时原样回传 `RoomMedia`。
|
||
- 一个 pending action 保存 `commandId + roomId + localFile + uploadedMedia`，超时重试不重建 command。
|
||
4. `RoomStateStore`
|
||
- 保存 `roomVersion`、`activeBackground`、`roomBorder`、`roomNameStyle` 和用户资料 `profiles`。
|
||
- HTTP 快照全量替换，IM 状态事件按 version 增量更新。
|
||
5. `RoomCustomMessageRouter`
|
||
- 按 `Ext/Desc/event_type` 分发，维护 `event_id` LRU。
|
||
- 图片维护独立 `message_id` 索引，用于发送者乐观消息与 IM 回执合并。
|
||
|
||
推荐上线顺序：
|
||
|
||
1. 先发布兼容解析：允许 `resource`、`active_background`、`room_border`、`room_name_style` 缺省。
|
||
2. 接入结构化 `VIP_BENEFIT_REQUIRED` 和统一 `command_id` 管理。
|
||
3. 接入用户资源 equip 与 VIP 素材真实 URL。
|
||
4. 接入背景专用上传、保存、切换及 IM。
|
||
5. 接入装扮 HTTP/IM 与到期隐藏。
|
||
6. 接入主页隐私两种分支。
|
||
7. 最后接入房间图片乐观消息、outbox IM 去重和异常恢复。
|
||
|
||
## 14. 联调验收清单
|
||
|
||
- Fami `/vip/packages`：有真实资源时返回完整 `resource`，未配置时字段省略。
|
||
- Lalu：旧背景 `image_url` 请求仍可用，新 Flutter 也可走专用协议。
|
||
- 资源 equip：相同 command/body 重放成功；换 entitlement 返回 `IDEMPOTENCY_CONFLICT`。
|
||
- 麦位动效：资源列表、appearance 和房间 `profiles[].mic_seat_animation` 的顶层 `format` 一致；后台未配格式时三处都省略该字段，Flutter 不从 URL 推断。
|
||
- VIP 到期后尝试重新 equip 历史资源：返回带四个 data 字段的 `VIP_BENEFIT_REQUIRED`。
|
||
- 背景：JPEG/PNG/GIF/WebP 正常；错误 MIME、APNG、超大小、超尺寸分别命中预期 code。
|
||
- 背景 upload 成功但未 save：背景列表不增加；save 后未 set：当前背景不变化。
|
||
- set 成功：HTTP、详情快照和 `room_background_changed` 三处一致。
|
||
- 装扮：非房主、无 entitlement、资源类型错、VIP 到期都不能写入 Room Cell。
|
||
- 彩色房名：HTTP 数组能渲染；IM 的数组字符串能二次解析。
|
||
- 主页统计隐藏：`target_stats_hidden=true` 时 JSON 中没有 `target_stats`。
|
||
- 匿名访问：访客列表没有真实 `visitor_user_id`；关闭匿名后历史记录仍匿名。
|
||
- 同一用户公开后匿名：列表可出现公开和匿名两个独立聚合。
|
||
- 房间图片：不在房、ban、禁言、公屏关闭、无权益均被拒绝；不要求上麦。
|
||
- 图片 send HTTP 成功但 IM 重投：同一 `event_id/message_id` 只显示一条。
|
||
- IM 状态版本断层、App 回前台或重连：详情快照可恢复最终背景和装扮。
|