# 语音房宝箱功能架构

本文定义语音房宝箱的产品规则、服务边界、App 接口、IM 事件、后台配置、奖励结算和验收边界。宝箱是房间内送礼驱动的互动玩法：用户在语音房送礼积攒能量，当前等级宝箱能量满后进入倒计时，倒计时结束时按房间快照抽奖并发放奖励。所有周期、重置和统计口径统一使用 UTC。

## Goals

| 目标 | 规则 |
| --- | --- |
| 礼物积攒能量 | 只有 `SendGift` 扣费成功并落 Room Cell 后才增加宝箱能量 |
| 7 级宝箱 | 每个 UTC 自然日从 1 级开始，最多开启 7 个等级 |
| 满能量倒计时开启 | 能量达到当前等级阈值后锁定本轮，按后台 `open_delay_ms` 设置 `open_at_ms` |
| 满能量播报 | 满能量后立即或按后台延迟发起播报，播报范围支持 `none/region/global` |
| 开箱抽奖 | `open_at_ms` 到达后快照房间在线用户、点火人和贡献第一，生成奖励结算事实 |
| 自动发奖 | 奖励由 activity-service 幂等抽奖并调用 wallet-service 发放资源组，不需要 App 手动领取 |
| UTC 重置 | 进度、贡献和已开启等级按 UTC 日期重置，不使用服务器本地时区或客户端时区 |

## Non-Goals

| 不做 | 原因 |
| --- | --- |
| 客户端提交能量、奖励或中奖结果 | 能量和奖励必须来自服务端扣费、配置和随机结果 |
| 在 room-service 保存钱包余额或发奖账本 | 钱包资产和资源发放仍由 wallet-service 拥有 |
| 由 activity-service 判断谁在房 | 房间 presence 和开箱快照必须由 Room Cell 产出 |
| 只用 Redis 保存宝箱进度 | MySQL snapshot/command log/宝箱表才是恢复来源 |
| 宝箱发奖失败时提前展示已到账 | 客户端只能展示 wallet-service 已成功发放的奖励 |

## Missing Interfaces

你的描述已经覆盖了核心 App 查询和 3 类 IM，但还缺这些接口和后台能力。

| 类型 | 接口 | 必要性 |
| --- | --- | --- |
| App 查询 | `GET /api/v1/rooms/{room_id}/treasure-chest` | 房间页主动同步宝箱配置、当前进度、倒计时、重置时间和最近结算 |
| App 查询 | `GET /api/v1/rooms/{room_id}/treasure-chest/rewards?round_id=...&scope=mine\|public` | 用户重连或错过 IM 后查询自己奖励、公开奖励摘要和发奖状态 |
| App 查询 | `JoinRoom` / `RoomDetail` 可内嵌 `treasure_chest_summary` | 避免进房首屏先空白，再等单独接口返回 |
| App 命令响应 | `SendGiftResponse` 增加 `treasure_chest_delta` | 送礼人成功送礼后立即更新能量和倒计时，不只依赖异步 IM |
| Admin 配置 | `GET/PUT /api/v1/admin/room-treasure/config` | 配置开关、7 级阈值、物料、倒计时、播报范围、奖励池和生效版本 |
| Admin 审计 | `GET /api/v1/admin/room-treasure/rounds` | 排查某房某天宝箱进度、点火人、贡献第一和状态 |
| Admin 审计 | `GET /api/v1/admin/room-treasure/reward-records` | 查询用户中奖、发奖、失败和重试记录 |
| Admin 补偿 | `POST /api/v1/admin/room-treasure/rounds/{round_id}/retry-settlement` | 对抽奖或 wallet 发放失败的轮次做幂等补偿 |
| Internal room | `ProcessDueTreasureChests` | cron 或 room-service worker 触发到期开箱，不能依赖单机内存 timer |
| Internal room | `ApplyTreasureChestSettlement` | activity-service 发奖完成后回写结算摘要，由 room-service 发房间发奖 IM |
| Internal activity | `ExecuteTreasureChestSettlement` 或消费 `RoomTreasureChestOpened` outbox | 按 Room Cell 快照做抽奖、写奖励记录、调用 wallet 发奖 |
| Internal wallet | 复用 `GrantResourceGroup`，后续补 `BatchGrantResourceGroup` | 每个在房用户都可能获奖，首版可逐个幂等发放，大房间需要批量优化 |

如果坚持“所有奖励完全自动到账”，不需要 App `claim` 接口；如果产品改成手动领取，必须新增 `POST /api/v1/rooms/{room_id}/treasure-chest/rewards/{reward_id}/claim`，并重新定义过期和未领取回收规则。

## Ownership

| 模块 | 拥有 | 不拥有 |
| --- | --- | --- |
| `room-service` | 宝箱进度、等级、状态机、点火人、贡献榜、开箱在线用户快照、房间宝箱 IM | 奖励实际入账、用户完整资料、全局/区域播报群成员 |
| `activity-service` | 宝箱奖励抽奖、奖励记录、发奖重试、全局/区域播报 outbox | Room Cell presence、房间核心状态 |
| `wallet-service` | 资源组发放、金币/钻石入账、钱包 outbox、幂等账本 | 宝箱进度和中奖资格 |
| `gateway-service` | App HTTP envelope、鉴权、聚合 room/activity/wallet 读模型 | 能量、抽奖和发奖事实 |
| `server/admin` | 后台权限、表单校验、审计、调用 owner service 管理 RPC | 直接写 room/activity/wallet 业务表 |

宝箱进度必须经过 Room Cell 命令链路。activity-service 可以消费 room outbox 做奖励结算和播报，但不能自己判断房间内用户、不能直接改宝箱进度。

## State Machine

```mermaid
stateDiagram-v2
  [*] --> disabled
  disabled --> charging: config enabled
  charging --> countdown: energy >= threshold
  countdown --> opening: now >= open_at_ms
  opening --> settling: RoomTreasureChestOpened outbox committed
  settling --> settled: rewards terminal
  settled --> charging: next level exists
  settled --> exhausted: level 7 settled
  exhausted --> charging: next UTC day
  charging --> charging: UTC daily reset
```

| 状态 | 语义 |
| --- | --- |
| `disabled` | 后台关闭，不累计能量，不发宝箱 IM |
| `charging` | 当前等级可累积能量 |
| `countdown` | 当前等级已满，`open_at_ms` 已确定，本轮进度、点火人和配置版本锁定 |
| `opening` | 到期开箱命令正在 Room Cell 内提交，快照参与用户 |
| `settling` | activity-service 正在抽奖和调用 wallet 发奖 |
| `settled` | 本轮奖励达到终态，房间已发结算 IM |
| `exhausted` | 当天 7 级都已开启，等下一个 UTC 自然日 |

`round_id` 建议稳定生成：

```text
treasure:<room_id>:<cycle_day>:<level>:<sequence>
```

`cycle_day` 固定为 UTC `YYYY-MM-DD`。同一房间同一 UTC 日同一等级只允许一个 active round。

## Energy Rules

| 规则 | 决策 |
| --- | --- |
| 能量来源 | 默认使用 `DebitGiftResponse.gift_point_added`；后台可配置 gift_id 级别倍率或覆盖值 |
| 生效条件 | wallet 扣费成功、room-service 已提交 `RoomGiftSent`、礼物能量值大于 0 |
| 幂等 | 同一 `SendGift.command_id` 只能增加一次宝箱能量 |
| 点火人 | 第一笔让当前等级 `progress >= threshold` 的送礼用户 |
| 贡献第一 | 当前 round 内累计能量最高用户；同分按首次达到该分值时间，再按 user_id 升序 |
| 溢出能量 | 单笔礼物超过当前等级剩余阈值时，只计入补满当前等级所需能量，多余能量作废 |
| 倒计时期间送礼 | 当前等级已经满能量，继续送礼不再增加宝箱能量，也不会排队到下一等级 |
| 7 级后送礼 | `exhausted` 后当天不再累计宝箱能量，礼物仍正常扣费、热度和榜单照常 |

溢出和倒计时期间的无效能量只用于审计，不计入当前 round 贡献、不计入下一等级进度、不改变点火人或贡献第一。送礼本身仍正常扣费、热度和房间礼物榜照常更新。

## Opening Rules

| 场景 | 处理 |
| --- | --- |
| 满能量 | Room Cell 把 round 切到 `countdown`，写 `RoomTreasureChestCountdownStarted` outbox |
| 播报 | activity-service 消费 countdown 事件，按配置发 `region/global` 播报；失败只重试播报，不回滚宝箱 |
| 到期开箱 | room-service worker 或 cron-service 触发 `ProcessDueTreasureChests`，由 Room Cell 提交开箱命令 |
| 开箱快照 | 以开箱命令执行时的 `OnlineUsers` 为准生成在房奖励参与人 |
| 房间关闭 | 如果已有 `countdown` round，CloseRoom 必须先提交开箱快照或取消策略；推荐先快照结算，再关闭房间 |
| 房间无人 | 在房奖励参与人为空；点火人和贡献第一仍按 round 贡献事实抽奖 |

点火人和贡献第一不要求开箱时仍在房或在线。只要用户在本 round 已经形成点火人或贡献第一事实，即使开箱前离房、断线或下线，也必须保留对应角色奖励；在房奖励仍只发给开箱快照里的 `OnlineUsers`。

## Reward Rules

| 奖励槽位 | 资格 | 默认是否可与其他槽位叠加 |
| --- | --- | --- |
| `in_room` | 开箱时 Room Cell `OnlineUsers` 内的每个用户 | 可叠加 |
| `top1` | 当前 round 贡献第一用户 | 可叠加 |
| `igniter` | 当前 round 点火人 | 可叠加 |

奖励配置按等级拆分，每个槽位是一个加权奖励池。奖励项推荐引用 `resource_group_id`，由 wallet-service 按资源组快照发放金币、钻石或资源权益。

```json
{
  "level": 3,
  "slot": "top1",
  "items": [
    {
      "reward_item_id": "lv3_top1_a",
      "resource_group_id": 12003,
      "weight": 9000,
      "display_name": "Top1 Reward",
      "icon_url": "https://cdn.example/reward.png"
    }
  ]
}
```

发奖幂等键：

```text
treasure_reward:<round_id>:<slot>:<user_id>
```

activity-service 对每个奖励记录先写 `treasure_chest_reward_records`，再调用 wallet-service。wallet 成功后才能把该记录标记为 `granted`。失败进入 `retryable/failed`，后台补偿必须复用同一幂等键。

## App Interfaces

### Get Treasure Chest

```http
GET /api/v1/rooms/{room_id}/treasure-chest
Authorization: Bearer <access_token>
```

Response `data`:

```json
{
  "enabled": true,
  "server_time_ms": 1779120000000,
  "reset_at_ms": 1779148800000,
  "config_version": 12,
  "current": {
    "cycle_day": "2026-05-19",
    "round_id": "treasure:lalu_room_1:2026-05-19:3:1",
    "level": 3,
    "status": "charging",
    "progress": 3600,
    "threshold": 10000,
    "progress_ppm": 360000,
    "opened_level_count": 2,
    "open_at_ms": 0,
    "igniter_user_id": "0",
    "top1_user_id": "10001"
  },
  "levels": [
    {
      "level": 1,
      "threshold": 3000,
      "cover_url": "https://cdn.example/chest/lv1/cover.png",
      "animation_url": "https://cdn.example/chest/lv1/idle.svga",
      "opening_animation_url": "https://cdn.example/chest/lv1/opening.svga",
      "opened_image_url": "https://cdn.example/chest/lv1/opened.png",
      "rewards": {
        "in_room": [],
        "top1": [],
        "igniter": []
      }
    }
  ],
  "latest_round": {
    "round_id": "treasure:lalu_room_1:2026-05-19:2:1",
    "level": 2,
    "status": "settled",
    "opened_at_ms": 1779116400000,
    "settled_at_ms": 1779116401200,
    "my_rewards": []
  }
}
```

规则：

- `levels` 固定返回 7 个等级的物料和奖励展示配置。
- `reset_at_ms` 是下一个 UTC 零点，不是用户本地零点。
- `progress_ppm = floor(progress * 1000000 / threshold)`，客户端不自行除浮点。
- 倒计时期间送礼和单笔溢出的无效能量不返回为下一等级进度；客户端只展示服务端返回的当前等级进度。

### Get Treasure Rewards

```http
GET /api/v1/rooms/{room_id}/treasure-chest/rewards?round_id=treasure:...&scope=mine
Authorization: Bearer <access_token>
```

Response `data`:

```json
{
  "round_id": "treasure:lalu_room_1:2026-05-19:3:1",
  "level": 3,
  "status": "settled",
  "reward_status": "granted",
  "items": [
    {
      "reward_record_id": "treasure_reward:treasure:lalu_room_1:2026-05-19:3:1:in_room:10001",
      "slot": "in_room",
      "user_id": "10001",
      "resource_group_id": 12001,
      "display_name": "Room Reward",
      "icon_url": "https://cdn.example/reward.png",
      "grant_status": "granted",
      "granted_at_ms": 1779120012000
    }
  ],
  "next_page_token": ""
}
```

`scope=public` 只返回公开摘要，例如点火人、贡献第一和最多 N 条可展示奖励；不要把所有用户的私派奖励大列表塞进 IM payload。

## IM Contracts

房间内宝箱 IM 仍走腾讯云房间群 `TIMCustomElem`，公共字段保持稳定：

```json
{
  "event_id": "room_treasure:...",
  "event_type": "room_treasure_progress_changed",
  "room_id": "lalu_room_1",
  "room_version": 102,
  "round_id": "treasure:lalu_room_1:2026-05-19:3:1",
  "level": 3,
  "cycle_day": "2026-05-19",
  "server_time_ms": 1779120000000
}
```

### Progress Changed

`event_type=room_treasure_progress_changed`

```json
{
  "sender_user_id": "10001",
  "gift_id": "rose",
  "gift_count": 10,
  "energy_added": 500,
  "invalid_energy": 0,
  "progress_before": 3100,
  "progress_after": 3600,
  "threshold": 10000,
  "status": "charging",
  "top1_user_id": "10001",
  "reset_at_ms": 1779148800000
}
```

### Countdown Started

`event_type=room_treasure_countdown_started`

```json
{
  "progress_after": 10000,
  "threshold": 10000,
  "igniter_user_id": "10002",
  "top1_user_id": "10001",
  "full_at_ms": 1779120000000,
  "open_at_ms": 1779120030000,
  "broadcast_scope": "region"
}
```

该事件进入 room outbox 后，activity-service 按配置生成全局或区域播报：

```json
{
  "event_id": "treasure_broadcast:treasure:lalu_room_1:2026-05-19:3:1",
  "broadcast_type": "room_treasure_ready",
  "scope": "region",
  "region_id": 1001,
  "room_id": "lalu_room_1",
  "round_id": "treasure:lalu_room_1:2026-05-19:3:1",
  "level": 3,
  "open_at_ms": 1779120030000,
  "action": {
    "type": "enter_room",
    "room_id": "lalu_room_1"
  }
}
```

### Chest Opened

`event_type=room_treasure_opened`

```json
{
  "opened_at_ms": 1779120030000,
  "participant_count": 86,
  "igniter_user_id": "10002",
  "top1_user_id": "10001",
  "settlement_status": "pending"
}
```

### Rewards Settled

`event_type=room_treasure_rewards_settled`

```json
{
  "settled_at_ms": 1779120031200,
  "reward_status": "granted",
  "participant_reward_count": 86,
  "top1_user_id": "10001",
  "igniter_user_id": "10002",
  "public_rewards": [
    {
      "slot": "top1",
      "user_id": "10001",
      "display_name": "Top1 Reward",
      "icon_url": "https://cdn.example/reward.png"
    },
    {
      "slot": "igniter",
      "user_id": "10002",
      "display_name": "Igniter Reward",
      "icon_url": "https://cdn.example/reward.png"
    }
  ],
  "full_result_required": true
}
```

群 IM 只承载公开摘要。用户自己的完整发奖结果通过 `GET /treasure-chest/rewards?scope=mine` 查询；后续接 notice-service 时，可以再补私有单聊或 inbox 通知。

## Admin Config

后台配置必须带 `config_version`，保存后只影响新 round；已经进入 `countdown/opening/settling` 的 round 使用锁定的配置快照。

| 字段 | 含义 |
| --- | --- |
| `enabled` | 总开关 |
| `energy_source` | 默认 `gift_point_added` |
| `open_delay_ms` | 满能量到开箱的倒计时 |
| `broadcast_enabled` | 是否满能量后播报 |
| `broadcast_scope` | `none/region/global` |
| `broadcast_delay_ms` | 满能量后多久发播报，默认 0 |
| `reward_stack_policy` | `allow_stack` 或 `priority_only` |
| `levels` | 7 个等级配置，包含阈值、物料 URL 和奖励池 |
| `gift_energy_rules` | gift_id 或 gift_type_code 的能量倍率、覆盖值和排除规则 |
| `effective_from_ms` | 配置开始生效时间，UTC epoch ms |
| `updated_by_admin_id` | 审计字段 |

每个等级必须配置：

| 字段 | 规则 |
| --- | --- |
| `level` | 1 到 7，不能缺级 |
| `threshold` | 大于 0，建议单调递增 |
| `cover_url` | 静态封面 |
| `animation_url` | 未开启待机动效 |
| `opening_animation_url` | 开启倒计时或开箱动效 |
| `opened_image_url` | 开启后静态图 |
| `in_room_rewards` | 在房用户奖励池 |
| `top1_rewards` | 贡献第一奖励池 |
| `igniter_rewards` | 点火人奖励池 |

奖励池保存时应校验：

- `resource_group_id` 必须存在且 active。
- 同一槽位权重总和必须大于 0。
- 展示字段可以保存快照，但发放仍以 wallet-service 资源组事实为准。
- 配置不能直接填写金币数量绕过资源组，除非新增明确的钱包奖励配置类型。

## Internal Events

建议在 `api/proto/events/room/v1/events.proto` 增加：

| Event | 生产方 | 消费方 | 用途 |
| --- | --- | --- | --- |
| `RoomTreasureChestProgressChanged` | room-service | Tencent IM/activity audit | 房间内进度 IM、审计 |
| `RoomTreasureChestCountdownStarted` | room-service | Tencent IM/activity broadcast | 房间倒计时 IM、区域/全局播报 |
| `RoomTreasureChestOpened` | room-service | activity-service | 奖励抽奖和发放输入，包含参与人快照和奖励配置快照 |
| `RoomTreasureChestSettlementApplied` | room-service | Tencent IM/audit | 发奖完成后的房间 IM |

`RoomTreasureChestOpened` 必须包含：

```text
round_id
cycle_day
level
config_version
room_id
visible_region_id
opened_at_ms
participant_user_ids
igniter_user_id
top1_user_id
contribution_top
reward_config_snapshot_json
```

activity-service 不反查 Room Cell 判断参与人，避免开奖时与房间状态发生竞态。

## Data Model Sketch

room-service 持久化：

```sql
room_treasure_rounds(
  app_code,
  room_id,
  cycle_day,
  round_id,
  level,
  status,
  progress,
  threshold,
  invalid_energy,
  config_version,
  igniter_user_id,
  top1_user_id,
  participant_count,
  full_at_ms,
  open_at_ms,
  opened_at_ms,
  settled_at_ms,
  reset_at_ms,
  created_at_ms,
  updated_at_ms
);

room_treasure_contributions(
  app_code,
  round_id,
  user_id,
  energy,
  first_contributed_at_ms,
  last_contributed_at_ms
);
```

activity-service 持久化：

```sql
treasure_chest_settlements(
  app_code,
  settlement_id,
  round_id,
  room_id,
  level,
  status,
  reward_config_snapshot_json,
  participant_count,
  created_at_ms,
  updated_at_ms
);

treasure_chest_reward_records(
  app_code,
  reward_record_id,
  settlement_id,
  round_id,
  slot,
  user_id,
  reward_item_id,
  resource_group_id,
  grant_command_id,
  grant_status,
  grant_id,
  retry_count,
  last_error,
  created_at_ms,
  updated_at_ms
);
```

Room Cell snapshot 也要包含当前宝箱轻量状态，保证节点恢复后不依赖 Redis 重建进度。表结构用于查询、due scan 和后台审计；command log 仍是写命令恢复的关键事实。

## Daily Reset

| 规则 | 决策 |
| --- | --- |
| 日期来源 | `time.Now().UTC()`，`cycle_day=YYYY-MM-DD` |
| 重置时间 | 每天 UTC `00:00:00.000` |
| 时间区间 | `[day_start_ms, next_day_start_ms)` |
| charging round | 到达新 UTC 日时清空进度、贡献和 queued energy，创建新 day level 1 round |
| countdown/opening/settling round | 已满能量的 round 继续开箱和发奖，使用原 `cycle_day` |
| exhausted | 下一个 UTC 日恢复 level 1 |

必须补 UTC 边界测试：`day_start_ms`、`next_day_start_ms - 1`、`next_day_start_ms`。不要重新引入 `time.Local`、`task_timezone` 或客户端时区。

## Implementation Flow

```mermaid
sequenceDiagram
  participant C as Client
  participant G as gateway-service
  participant R as room-service
  participant W as wallet-service
  participant A as activity-service
  participant IM as Tencent IM

  C->>G: POST /api/v1/rooms/gift/send
  G->>R: SendGift(command_id)
  R->>W: DebitGift(command_id)
  W-->>R: gift_point_added, receipt
  R->>R: Room Cell updates heat/rank/treasure
  R-->>C: SendGiftResponse + treasure summary
  R-->>IM: room_treasure_progress_changed
  alt energy full
    R-->>IM: room_treasure_countdown_started
    R-->>A: room outbox RoomTreasureChestCountdownStarted
    A-->>IM: region/global room_treasure_ready broadcast
  end
  R->>R: ProcessDueTreasureChests at open_at_ms
  R-->>IM: room_treasure_opened
  R-->>A: room outbox RoomTreasureChestOpened
  A->>A: draw rewards idempotently
  A->>W: GrantResourceGroup per reward
  W-->>A: grant result
  A->>R: ApplyTreasureChestSettlement(summary)
  R-->>IM: room_treasure_rewards_settled
```

`ApplyTreasureChestSettlement` 是 gRPC/protobuf 边界，不允许 activity-service import room-service `internal` 包。它只提交结算摘要和可展示公共结果，不让 activity-service 改写宝箱进度。

## Failure Handling

| 失败 | 处理 |
| --- | --- |
| wallet DebitGift 失败 | 不增加能量，不写宝箱进度，不发宝箱 IM |
| room outbox 投递 IM 失败 | 房间状态已提交，outbox 重试或死信；App 可用 GET 接口补状态 |
| broadcast 失败 | activity broadcast outbox 重试，不影响开箱 |
| due open worker 宕机 | MySQL `open_at_ms/status` 可被下一轮 worker/cron 重新扫描 |
| activity 抽奖失败 | settlement 保持 `retryable`，不发“已发奖” IM |
| wallet 发奖部分失败 | 成功记录保持 granted，失败记录重试；房间 IM 标记 `partial` 或等待全部终态后再发 |
| App 错过 IM | `GET /treasure-chest` 和 `GET /treasure-chest/rewards` 补齐 |

## Tests

必须覆盖：

| 场景 | 验证 |
| --- | --- |
| 送礼幂等 | 同一 `command_id` 重试不重复加能量 |
| 阈值边界 | `progress = threshold - 1` 不点火，`progress = threshold` 点火一次 |
| 溢出能量 | 单笔礼物超过阈值时只补满当前等级，剩余能量作废且不进入下一等级 |
| 倒计时送礼 | countdown/opening/settling 期间送礼不增加宝箱能量，不改变点火人和 top1 |
| 倒计时开箱 | `open_at_ms` 前不开，等于或超过时只开一次 |
| 在线快照 | 开箱时在线用户获得 in_room 抽奖资格，离房用户不获得 in_room 奖励 |
| top1/igniter | 同分 tie-break 固定；离房、断线或下线后仍结算角色奖励 |
| UTC 重置 | 覆盖 UTC 日开始、结束前一毫秒、结束边界 |
| room close | countdown 后关房不会丢掉已满宝箱奖励 |
| 发奖幂等 | reward_record 重试不重复发资源组 |
| 播报范围 | `none/region/global` 分别不发、发区域、发全局 |
| IM 补偿 | outbox 重试不会产生不同 event_id 的重复客户端消息 |