296 lines
11 KiB
Markdown
296 lines
11 KiB
Markdown
# 语音房火箭接口对接
|
||
|
||
## 规则
|
||
|
||
- 火箭最高 5 级。
|
||
- 房间送礼成功后，按礼物 `heat_value` 增加当前等级火箭燃料。
|
||
- 当前等级满后立刻点火，并把该等级火箭放入 `pending_launches` 等待发射。
|
||
- 点火后下一等级马上开始累计燃料。
|
||
- 单次送礼超过当前等级阈值时，超过部分直接作废，不顺延到下一等级。
|
||
- 发射延迟由后台 `launch_delay_ms` 配置。
|
||
- 发射结算三类奖励：点火人、贡献第一、在房用户。在房用户按发射瞬间房间 presence 抽奖。
|
||
|
||
## 获取火箭
|
||
|
||
地址：`GET /api/v1/rooms/{room_id}/rocket`
|
||
|
||
参数：
|
||
|
||
| 参数 | 位置 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `room_id` | path | 是 | 房间 ID |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `enabled` | 火箭是否开启 |
|
||
| `levels` | 1 到 5 级配置 |
|
||
| `levels[].fuel_threshold` | 等级燃料阈值 |
|
||
| `levels[].cover_url` | 火箭小封面图 |
|
||
| `levels[].animation_url` | 常态动效 |
|
||
| `levels[].launch_animation_url` | 发射动效 |
|
||
| `levels[].launched_image_url` | 发射后图 |
|
||
| `levels[].in_room_rewards` | 在房奖励候选 |
|
||
| `levels[].top1_rewards` | 贡献第一奖励候选 |
|
||
| `levels[].igniter_rewards` | 点火人奖励候选 |
|
||
| `levels[].*_rewards[].resource_group_id` | 奖励资源组 ID |
|
||
| `levels[].*_rewards[].resource_group` | 奖励资源组详情 |
|
||
| `levels[].*_rewards[].resource_group.items` | 资源组明细 |
|
||
| `levels[].*_rewards[].resource_group.items[].item_type` | `wallet_asset` 或 `resource` |
|
||
| `levels[].*_rewards[].resource_group.items[].wallet_asset_type` | 金币等奖励资产类型，例如 `COIN` |
|
||
| `levels[].*_rewards[].resource_group.items[].wallet_asset_amount` | 金币等奖励数量 |
|
||
| `levels[].*_rewards[].resource_group.items[].resource` | 聊天气泡、麦位特效等资源素材 |
|
||
| `levels[].*_rewards[].resource_group.items[].resource.resource_type` | 资源类型，例如 `chat_bubble`、`mic_effect` |
|
||
| `levels[].*_rewards[].resource_group.items[].resource.asset_url` | 资源主素材 |
|
||
| `levels[].*_rewards[].resource_group.items[].resource.preview_url` | 资源预览图 |
|
||
| `levels[].*_rewards[].resource_group.items[].resource.animation_url` | 资源动效 |
|
||
| `levels[].*_rewards[].resource_group.items[].duration_ms` | 资源有效期毫秒，`0` 表示永久 |
|
||
| `state.current_level` | 当前正在累计的等级 |
|
||
| `state.current_fuel` | 当前等级已累计燃料 |
|
||
| `state.fuel_threshold` | 当前等级阈值 |
|
||
| `state.status` | `charging` 或 `completed` |
|
||
| `state.rocket_id` | 当前正在累计火箭 ID |
|
||
| `state.pending_launches` | 已点火待发射火箭列表 |
|
||
| `state.pending_launches[].rocket_id` | 待发射火箭 ID |
|
||
| `state.pending_launches[].level` | 待发射等级 |
|
||
| `state.pending_launches[].ignited_at_ms` | 点火 UTC 毫秒 |
|
||
| `state.pending_launches[].launch_at_ms` | 预计发射 UTC 毫秒 |
|
||
| `state.pending_launches[].top1_user_id` | 点火时锁定贡献第一 |
|
||
| `state.pending_launches[].igniter_user_id` | 点火人 |
|
||
| `state.pending_launches[].cover_url` | 小封面图 |
|
||
| `state.last_rewards` | 最近一次发射奖励结果 |
|
||
| `state.last_rewards[].resource_group_id` | 本次中奖资源组 ID |
|
||
| `state.last_rewards[].resource_group` | 本次中奖资源组详情，字段同上 |
|
||
| `server_time_ms` | 服务端 UTC 毫秒 |
|
||
|
||
`levels[].*_rewards` 表示 `in_room_rewards`、`top1_rewards`、`igniter_rewards` 三个奖励池。客户端展示金币数量、奖励天数、聊天气泡、麦位特效时，直接读 `resource_group.items`。
|
||
|
||
## 送礼
|
||
|
||
地址：`POST /api/v1/rooms/gift/send`
|
||
|
||
参数：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `room_id` | 是 | 房间 ID |
|
||
| `command_id` | 是 | 客户端本次送礼幂等 ID |
|
||
| `target_type` | 否 | 默认 `user` |
|
||
| `target_user_id` | 否 | 单收礼用户 ID |
|
||
| `target_user_ids` | 否 | 多收礼用户 ID |
|
||
| `gift_id` | 是 | 礼物 ID |
|
||
| `gift_count` | 是 | 礼物数量 |
|
||
| `pool_id` | 否 | 幸运礼物奖池 ID |
|
||
|
||
返回值：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `result` | 命令提交结果 |
|
||
| `billing_receipt_id` | 钱包扣费回执 |
|
||
| `room_heat` | 最新房间热度 |
|
||
| `gift_rank` | 最新房间礼物榜 |
|
||
| `rocket` | 送礼后的火箭状态，字段同 `state` |
|
||
| `lucky_gift` | 本次送礼聚合幸运礼物结果 |
|
||
| `lucky_gifts` | 多目标送礼时每个目标的幸运礼物结果 |
|
||
|
||
## 后台配置
|
||
|
||
地址：`GET /v1/admin/activity/room-rocket/config`
|
||
|
||
参数：无
|
||
|
||
返回值：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `enabled` | 是否开启 |
|
||
| `fuelSource` | 固定为 `heat_value` |
|
||
| `launchDelayMs` | 点火后延迟发射毫秒 |
|
||
| `broadcastEnabled` | 是否发区域或全局飘屏 |
|
||
| `broadcastScope` | `region`、`global`、`none` |
|
||
| `rewardStackPolicy` | `allow_stack` 或 `priority_only` |
|
||
| `levels` | 5 级配置 |
|
||
| `giftFuelRules` | 礼物燃料规则 |
|
||
|
||
地址：`PUT /v1/admin/activity/room-rocket/config`
|
||
|
||
参数：
|
||
|
||
| 参数 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `enabled` | 是 | 是否开启 |
|
||
| `fuelSource` | 是 | 固定传 `heat_value` |
|
||
| `launchDelayMs` | 是 | 点火后延迟发射毫秒 |
|
||
| `broadcastEnabled` | 是 | 是否发飘屏 |
|
||
| `broadcastScope` | 是 | `region`、`global`、`none` |
|
||
| `broadcastDelayMs` | 是 | 保留字段，当前点火后立即入 outbox |
|
||
| `rewardStackPolicy` | 是 | `allow_stack` 或 `priority_only` |
|
||
| `levels` | 是 | 必须 5 级 |
|
||
| `levels[].fuelThreshold` | 是 | 等级阈值 |
|
||
| `levels[].coverUrl` | 否 | 小封面图 |
|
||
| `levels[].animationUrl` | 否 | 常态动效 |
|
||
| `levels[].launchAnimationUrl` | 否 | 发射动效 |
|
||
| `levels[].launchedImageUrl` | 否 | 发射后图 |
|
||
| `levels[].inRoomRewards` | 否 | 在房奖励池 |
|
||
| `levels[].top1Rewards` | 否 | 贡献第一奖励池 |
|
||
| `levels[].igniterRewards` | 否 | 点火人奖励池 |
|
||
| `giftFuelRules[].giftId` | 否 | 指定礼物 ID |
|
||
| `giftFuelRules[].giftTypeCode` | 否 | 指定礼物类型 |
|
||
| `giftFuelRules[].multiplierPpm` | 否 | 燃料倍率，1 倍为 `1000000` |
|
||
| `giftFuelRules[].fixedFuel` | 否 | 固定燃料 |
|
||
| `giftFuelRules[].excluded` | 否 | 是否排除该礼物 |
|
||
|
||
返回值：同获取后台配置。
|
||
|
||
## 房间 IM
|
||
|
||
来源：腾讯云 IM 房间群。
|
||
|
||
基础字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `TIMCustomElem.Ext` | `room_system_message` |
|
||
| `event_type` | 事件类型 |
|
||
| `room_id` | 房间 ID |
|
||
| `event_id` | 消息 ID |
|
||
| `occurred_at_ms` | 服务端 UTC 毫秒 |
|
||
|
||
### room_rocket_fuel_changed
|
||
|
||
用途：刷新当前等级进度。
|
||
|
||
字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `rocket_id` | 当前累计火箭 ID |
|
||
| `level` | 当前累计等级 |
|
||
| `added_fuel` | 本次理论燃料 |
|
||
| `effective_added_fuel` | 本次实际计入燃料 |
|
||
| `overflow_fuel` | 本次作废燃料 |
|
||
| `current_fuel` | 当前等级燃料 |
|
||
| `fuel_threshold` | 当前等级阈值 |
|
||
| `status` | `charging` 或本次满阈值时的 `ignited` |
|
||
| `gift_id` | 礼物 ID |
|
||
| `gift_count` | 礼物数量 |
|
||
|
||
### room_rocket_ignited
|
||
|
||
用途：当前等级满阈值，加入待发射队列；客户端立即把下一等级作为当前进度。
|
||
|
||
字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `rocket_id` | 待发射火箭 ID |
|
||
| `level` | 待发射等级 |
|
||
| `rocket_level` | 同 `level` |
|
||
| `room_short_id` | 房间短号 |
|
||
| `rocket_cover_url` | 小封面图 |
|
||
| `current_fuel` | 满阈值燃料 |
|
||
| `fuel_threshold` | 满阈值 |
|
||
| `ignited_at_ms` | 点火时间 |
|
||
| `launch_at_ms` | 预计发射时间 |
|
||
| `reset_at_ms` | UTC 日重置时间 |
|
||
| `top1_user_id` | 点火时贡献第一 |
|
||
| `igniter_user_id` | 点火人 |
|
||
|
||
### room_rocket_launched
|
||
|
||
用途：火箭已到点发射，客户端播放发射表现。
|
||
|
||
字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `rocket_id` | 已发射火箭 ID |
|
||
| `level` | 已发射等级 |
|
||
| `next_level` | 当前正在累计等级 |
|
||
| `launched_at_ms` | 发射时间 |
|
||
| `top1_user_id` | 贡献第一 |
|
||
| `igniter_user_id` | 点火人 |
|
||
| `rewards_json` | 奖励摘要 |
|
||
|
||
## 区域或全局飘屏 IM
|
||
|
||
来源：腾讯云 IM 区域群或全局群。
|
||
|
||
基础字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `TIMCustomElem.Ext` | `im_broadcast` |
|
||
| `TIMCustomElem.Desc` | `room_rocket` |
|
||
|
||
消息体：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `broadcast_type` | `room_rocket` |
|
||
| `scope` | `region` 或 `global` |
|
||
| `room_id` | 房间 ID |
|
||
| `room_short_id` | 房间短号 |
|
||
| `rocket_id` | 待发射火箭 ID |
|
||
| `rocket_level` | 火箭等级 |
|
||
| `rocket_cover_url` | 小封面图 |
|
||
| `launch_at_ms` | 预计发射时间 |
|
||
| `igniter.user_id` | 点火人用户 ID |
|
||
| `igniter.short_id` | 点火人短 ID |
|
||
| `igniter.nickname` | 点火人昵称 |
|
||
| `igniter.avatar` | 点火人头像 |
|
||
|
||
## 奖励房间 IM
|
||
|
||
来源：腾讯云 IM 房间群。
|
||
|
||
基础字段：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `TIMCustomElem.Ext` | `im_broadcast` |
|
||
| `TIMCustomElem.Desc` | `room_rocket_reward_granted` |
|
||
|
||
消息体：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `broadcast_type` | `room_rocket_reward_granted` |
|
||
| `scope` | `room` |
|
||
| `room_id` | 房间 ID |
|
||
| `rocket_id` | 已发射火箭 ID |
|
||
| `rocket_level` | 已发射等级 |
|
||
| `rewards` | 本次所有获得奖励的人 |
|
||
| `rewards[].reward_role` | `in_room`、`top1`、`igniter` |
|
||
| `rewards[].user.user_id` | 用户 ID |
|
||
| `rewards[].user.short_id` | 用户短 ID |
|
||
| `rewards[].user.nickname` | 用户昵称 |
|
||
| `rewards[].user.avatar` | 用户头像 |
|
||
| `rewards[].resource_group_id` | 资源组 ID |
|
||
| `rewards[].display_name` | 奖励展示名 |
|
||
| `rewards[].icon_url` | 奖励图标 |
|
||
| `rewards[].grant_id` | 发奖回执 |
|
||
| `rewards[].status` | 发奖状态 |
|
||
|
||
奖励 IM 用于通知本次哪些人中奖。top1 和点火人命中后会发完整配置池，同一用户可能同时收到多条 `top1`、`igniter` 和 1 条在房随机奖励。需要渲染金币数量、奖励天数、聊天气泡或麦位特效素材时，收到 IM 后调用 `GET /api/v1/rooms/{room_id}/rocket`，读取 `state.last_rewards[].resource_group`。
|
||
|
||
## 客户端处理
|
||
|
||
- 进房先调 `GET /api/v1/rooms/{room_id}/rocket`。
|
||
- 送礼成功优先用返回的 `rocket` 刷新状态。
|
||
- 收到 `room_rocket_fuel_changed` 刷新进度。
|
||
- 收到 `room_rocket_ignited` 把该火箭加入待发射队列，并显示下一等级当前进度。
|
||
- 收到 `room_rocket_launched` 播放发射表现。
|
||
- 收到 `room_rocket_reward_granted` 展示本次所有中奖人和奖励。
|
||
- 如果 IM 丢失或乱序，用 GET 接口兜底。
|
||
- 不要用普通 `room_gift_sent` 自行推算火箭燃料。
|
||
|
||
## 高频和延迟处理
|
||
|
||
- 送礼只同步写 Room Cell 状态和 room outbox，不同步请求腾讯 IM。
|
||
- 房间进度 IM 走 room outbox 补偿投递，失败会重试。
|
||
- 点火后延迟发射通过 RocketMQ delayed wakeup 唤醒；到点后 room-service 重新校验 `rocket_id`、`level`、`launch_at_ms`、UTC 重置边界。
|
||
- 奖励 IM 一次性包含所有中奖人，避免按用户逐条发 IM。
|