# 语音房火箭功能架构

## 服务边界

- `room-service` 是火箭进度、点火、待发射队列和奖励结算 owner。
- `gateway-service` 只提供 App HTTP 入口和鉴权后的协议转换；`GET /api/v1/rooms/{room_id}/rocket` 会按奖励 `resource_group_id` 查询 wallet-service 并嵌入 `resource_group.items`。
- `server/admin` 只读写 `room-service` 内部配置接口，不直连 room 数据库。
- `wallet-service` 负责资源组发放。
- `activity-service` 负责区域/全局飘屏和带用户资料的奖励房间 IM。
- 腾讯云 IM 负责房间群、区域群和全局群投递。

## 状态模型

`RoomRocketState` 保存当前正在累计的火箭和已点火待发射队列。

| 字段 | 说明 |
| --- | --- |
| `current_level` | 当前正在累计的等级，最高 5 |
| `current_fuel` | 当前等级燃料 |
| `fuel_threshold` | 当前等级阈值 |
| `status` | `charging` 或 `completed` |
| `rocket_id` | 当前正在累计的火箭 ID |
| `pending_launches` | 已点火、等待延迟发射的火箭 |
| `last_rewards` | 最近一次发射奖励结果 |

`pending_launches` 中每一项锁定：

| 字段 | 说明 |
| --- | --- |
| `rocket_id` | 本枚火箭幂等 ID |
| `level` | 点火等级 |
| `fuel_threshold` | 点火阈值 |
| `ignited_at_ms` | 点火时间 |
| `launch_at_ms` | 预计发射时间 |
| `reset_at_ms` | UTC 日重置时间 |
| `top1_user_id` | 点火时贡献第一 |
| `igniter_user_id` | 点火人 |
| `config_version` | 点火配置版本 |
| `cover_url` | 小封面图 |

## 送礼加燃料

1. `SendGift` 先调用 wallet 扣费。
2. 扣费成功后，Room Cell 串行更新热度、礼物榜和火箭。
3. 燃料来自 wallet 返回的 `heat_value`。
4. 当前等级未满时，增加 `min(本次燃料, 剩余阈值)`。
5. 超过阈值的燃料直接写入 `overflow_fuel`，不进入下一等级。
6. 当前等级满后：
   - 写入 `RoomRocketFuelChanged`。
   - 写入 `RoomRocketIgnited`。
   - 将当前火箭追加到 `pending_launches`。
   - 如果未到 5 级，立刻把当前状态切到下一等级，`current_fuel=0`。
   - 如果 5 级已满，状态切到 `completed`，UTC 重置前不再累计新火箭。

## 发射结算

1. `RoomRocketIgnited` 被 outbox worker 处理后，安排 RocketMQ delayed wakeup。
2. 本地扫描 worker 也会扫描已加载且仍持有 lease 的 Room Cell，作为兜底。
3. 到点后 `LaunchRoomRocket` 命令重新加载 Room Cell。
4. 命令必须校验：
   - `rocket_id` 存在于 `pending_launches`。
   - `level` 匹配。
   - `launch_at_ms <= now_ms`。
   - `now_ms < reset_at_ms`。
5. 结算时按发射瞬间 `OnlineUsers` 抽在房奖励。
6. `top1` 和 `igniter` 使用点火时锁定的用户，离房后仍发对应奖励。
7. 发奖完成后移除该 `pending_launches` 项，当前正在累计的火箭不被发射命令推进。

## 奖励

| 奖励 | 用户来源 |
| --- | --- |
| 点火人奖励 | `pending_launches[].igniter_user_id` |
| 贡献第一奖励 | `pending_launches[].top1_user_id` |
| 在房奖励 | 发射命令执行时 Room Cell `OnlineUsers` |

发放规则：

| 奖励 | 规则 |
| --- | --- |
| 在房奖励 | 每个在线用户从 `inRoomRewards` 按权重随机抽 1 个 |
| 贡献第一奖励 | top1 用户获得 `top1Rewards` 配置池内全部奖励 |
| 点火人奖励 | 点火用户获得 `igniterRewards` 配置池内全部奖励 |

同一用户同时是 top1 和点火人时，top1 池和点火人池继续叠加；如果该用户发射瞬间仍在房间，也会再拿 1 个在房随机奖励。

## IM

| 事实 | IM | 投递方 |
| --- | --- | --- |
| `RoomRocketFuelChanged` | `room_rocket_fuel_changed` | room-service IM bridge |
| `RoomRocketIgnited` | `room_rocket_ignited` | room-service IM bridge |
| `RoomRocketIgnited` | `room_rocket` 区域/全局飘屏 | activity-service |
| `RoomRocketLaunched` | `room_rocket_launched` | room-service IM bridge |
| `RoomRocketRewardGranted` | `room_rocket_reward_granted` 房间奖励 IM | activity-service |

奖励 IM 由 activity-service 查询用户公开资料后组装，包含头像、昵称、短 ID 和奖励信息。room-service 不反查 user-service。
奖励资源组内容不写入 Room Cell；客户端需要金币数量、有效期、聊天气泡或麦位特效素材时，通过 rocket GET 接口读取展开后的 `resource_group`。

## 高频处理

- Room Cell 串行处理送礼命令，所以同房高频送礼不会并发写乱进度。
- 满阈值时只把火箭追加到 `pending_launches`，不会阻塞下一等级继续累计。
- 房间状态 IM 通过 room outbox 补偿投递，不在送礼主链路同步调用腾讯 IM。
- 奖励 IM 合并为一条消息，`rewards` 内包含所有中奖人，避免按用户逐条堆积。
- RocketMQ delayed wakeup 只负责唤醒，最终发射仍由 Room Cell 命令校验。

## UTC 重置

- 火箭周期按 UTC 自然日。
- 到达 `reset_at_ms` 后，查询或下一次送礼会投影为 1 级新进度。
- 跨过 UTC 日界仍未发射的待发射火箭不结算。

## 后台配置

配置表：`room_rocket_configs`

| 字段 | 说明 |
| --- | --- |
| `enabled` | 是否开启 |
| `fuel_source` | 固定 `heat_value` |
| `launch_delay_ms` | 点火到发射延迟 |
| `broadcast_enabled` | 是否发飘屏 |
| `broadcast_scope` | `region`、`global`、`none` |
| `reward_stack_policy` | 历史兼容字段；当前特殊身份奖励按上方规则叠加 |
| `levels_json` | 5 级阈值、物料和奖励池 |
| `gift_fuel_rules_json` | 礼物燃料规则 |

`levels_json` 字段使用 `fuelThreshold`、`coverUrl`、`animationUrl`、`launchAnimationUrl`、`launchedImageUrl`、`inRoomRewards`、`top1Rewards`、`igniterRewards`。