# 语音房大额礼物全局飘窗方案

整理时间：2026-05-06  
适用范围：语音房普通大额礼物飘窗；只在一级页面 `home / explore / message / me` 展示；点击进入对应房间。  
本轮只做方案整理，不改业务代码。

## 1. 需求目标

在用户送出大额礼物时，新增一个顶部飘窗，展示类似：

> 用户 A 在房间 B 送了 C 礼物

要求：

- 礼物类型：普通礼物大额送礼，明确排除幸运礼物、魔法礼物等走 `giveLuckyGift` 的礼物。
- 展示范围：全局一级页面，但只限首页主框架内的四个 Tab：`home / explore / message / me`。
- 不在语音房页面、二级页面、设置页、充值页、聊天详情页等页面展示。
- 点击飘窗后进入具体房间。
- 飘窗位置沿用当前幸运礼物/礼物飘屏顶部位置。

## 2. 当前代码现状

### 2.1 顶部飘窗能力已存在

现有飘窗由 `OverlayManager` 统一调度：

- 文件：`lib/shared/data_sources/sources/local/floating_screen_manager.dart`
- 入口：`OverlayManager().addMessage(SCFloatingMessage)`
- 队列：`SCPriorityQueue<SCFloatingMessage>`，按 `priority` 排序。
- 位置：`OverlayEntry` 使用 `Align(topStart)`，再 `Transform.translate(offset: Offset(0, 70.w))`。
- 动画组件：
  - `type = 0`：`FloatingLuckGiftScreenWidget`
  - `type = 1`：`FloatingGiftScreenWidget`
  - `type = 2`：游戏中奖
  - `type = 3`：火箭
  - `type = 4`：红包
  - `type = 5`：VIP 进房

现有 `FloatingLuckGiftScreenWidget` 和 `FloatingGiftScreenWidget` 都已经支持：

- 从右往左飘过。
- 左滑快速关闭。
- 点击后调用 `SCRoomUtils.goRoom(roomId, context, fromFloting: true)` 进入房间。

### 2.2 现有普通礼物飘窗是房间内逻辑

普通礼物发送成功后会进入 `GiftPage.sendGiftMsg(...)`：

- 文件：`lib/modules/gift/gift_page.dart`
- 当前判断：`gift.giftCandy * quantity > 9999` 时创建 `SCFloatingMessage(type: 1)`。
- 当前内容：用户 A 送给用户 B 礼物，字段偏向 `toUserName / toUserAvatarUrl`。
- 当前触发范围：发送者本地和当前房间 RTM 收到 `SCRoomMsgType.gift` 后触发。

这条逻辑不适合直接作为“全局大额礼物飘窗”：

- 它是房间消息，不是全服消息。
- 它按收礼人循环，可能一次多目标送礼触发多条。
- UI 文案是“send to 某用户”，不是“在房间 B 送了 C 礼物”。
- `OverlayManager._shouldDisplayMessage(...)` 当前对 `type = 0 / 1 / 5` 要求必须匹配当前房间 ID，否则不展示。

### 2.3 全服广播通道已存在

RTM 初始化后会加入全服广播群：

- 文件：`lib/services/audio/rtm_manager.dart`
- `init(...)` 中调用 `joinBigBroadcastGroup()`
- 全服消息在 `_newBroadCastMsgRecv(...)` 处理
- 当前已处理：
  - `GAME_LUCKY_GIFT`
  - 游戏中奖
  - 火箭
  - 红包

因此新增大额普通礼物全局飘窗时，最合适的入口是全服广播群，而不是房间群消息。

## 3. 推荐总体方案

推荐采用：

```mermaid
flowchart LR
  A["用户在房间送普通礼物"] --> B["后端校验送礼成功"]
  B --> C{"是否普通大额礼物"}
  C -- "否" --> D["只走现有房间送礼消息"]
  C -- "是" --> E["后端推送 BIG_GIFT 到全服广播群"]
  E --> F["客户端 _newBroadCastMsgRecv 接收"]
  F --> G{"当前是否首页四个一级 Tab"}
  G -- "否" --> H["丢弃，不入队"]
  G -- "是" --> I["OverlayManager 入队展示顶部飘窗"]
  I --> J["点击 SCRoomUtils.goRoom(roomId)"]
```

核心点：

- 大额判断放后端做，前端只负责展示，避免客户端伪造全服大礼物消息。
- 前端新增独立消息类型，例如 `BIG_GIFT`，不复用幸运礼物 `GAME_LUCKY_GIFT`。
- 前端新增独立飘窗类型，例如 `SCFloatingMessage.type = 6`，避免影响当前房间内 `type = 1` 的普通礼物飘窗。
- 展示作用域由 `OverlayManager` 或主框架路由状态控制，只允许首页四 Tab 展示。

## 4. 服务端数据建议

建议后端在普通礼物接口送礼成功后判断是否需要推送全服广播：

- 接口链路：`/gift/batch`，前端对应 `SCChatRoomRepository.giveGift(...)`。
- 排除链路：`/gift/give/lucky-gift`，前端对应 `giveLuckyGift(...)`。
- 推荐阈值：沿用客户端现有房间内逻辑 `totalCoins >= 10000`，最终以产品/后端配置为准。
- 推荐只推送一次送礼行为，不按收礼人数量重复推送。

推荐全服广播 payload：

```json
{
  "type": "BIG_GIFT",
  "data": {
    "eventId": "giftSendRecordId or unique id",
    "roomId": "room id",
    "roomName": "room name",
    "sendUserId": "sender user id",
    "sendUserName": "sender nickname",
    "sendUserAvatar": "sender avatar",
    "giftId": "gift id",
    "giftName": "gift name",
    "giftPhoto": "gift cover url",
    "giftQuantity": 1,
    "giftCandy": 10000,
    "totalCoins": 10000,
    "timestamp": 1710000000000
  }
}
```

字段说明：

- `eventId`：用于客户端去重。没有则用 `roomId + sendUserId + giftId + giftQuantity + timestamp` 做兜底 key。
- `roomId`：点击飘窗进房必须字段。
- `roomName`：满足“在房间 B”的展示需求。
- `giftName / giftPhoto`：满足“送了 C 礼物”的展示和礼物图标展示。
- `totalCoins`：可用于优先级、样式分级或埋点。

## 5. 前端改造点

### 5.1 新增大额礼物广播模型

建议新增模型：

- `lib/shared/business_logic/models/res/sc_big_gift_broadcast_push.dart`

字段对应服务端 payload。不要把所有字段硬塞进 `SCBroadCastLuckGiftPush`，幸运礼物模型语义不同。

也可以扩展 `SCFloatingMessage`：

- 新增 `roomName`
- 新增 `giftName`
- 新增 `eventId`
- 保留 `roomId / userName / userAvatarUrl / giftUrl / giftId / number / coins / priority`

### 5.2 RTM 全服广播接入

在 `RealTimeMessagingManager._newBroadCastMsgRecv(...)` 增加：

```dart
} else if (type == "BIG_GIFT") {
  final push = SCBigGiftBroadcastPush.fromJson(data);
  _handleBigGiftGlobalNews(push);
}
```

`_handleBigGiftGlobalNews(...)` 推荐职责：

- 校验 `roomId`、`sendUserName`、`giftName` 至少有可展示值。
- 排除幸运礼物或服务端标记的非普通礼物。
- 去重。
- 组装 `SCFloatingMessage(type: 6, priority: 900, ...)`。
- 调用 `OverlayManager().addMessage(...)`。

优先级建议：

- 幸运礼物：当前 `priority = 1000`。
- 大额普通礼物：建议 `priority = 900`。
- 普通房间礼物本地飘窗：保持默认或现有逻辑。

### 5.3 新增大额礼物飘窗 Widget

建议新增：

- `lib/ui_kit/widgets/room/floating/floating_big_gift_screen_widget.dart`

原因：

- 当前 `FloatingGiftScreenWidget` 展示的是“用户 A sendTo 用户 B + 礼物图标 x 数量”。
- 新需求是“用户 A 在房间 B 送了 C 礼物”。
- 新增 Widget 可以复用现有动画、点击、左滑关闭逻辑，但不影响房间内普通礼物飘窗。

UI 建议：

- 保持同一位置和相近尺寸：`height 54.w` 左右，`width 320.w - 350.w`。
- 左侧：送礼用户头像和昵称。
- 中间：房间名和文案，例如 `在 {roomName} 送出`。
- 右侧：礼物图标 + 礼物名，可保留 `x{quantity}`。
- 长昵称、长房间名、长礼物名使用 `TextOverflow.ellipsis` 或局部跑马灯，避免遮挡。
- RTL 语言需要检查布局方向，至少保持点击和左滑逻辑与现有组件一致。

`OverlayManager._buildScreenWidget(...)` 增加：

```dart
case 6:
  return FloatingBigGiftScreenWidget(
    message: message,
    onAnimationCompleted: onComplete,
  );
```

### 5.4 展示作用域：只允许首页四 Tab

当前 `OverlayManager` 是根 Overlay 展示，天然能覆盖全 App。需要新增“允许展示作用域”，否则可能在二级页、房间页也展示。

推荐方案：由 `SCIndexPage` 作为主框架控制作用域。

实现思路：

- `SCIndexPage` 接入 `RouteAware`，订阅全局 `routeObserver`。
- 当 `SCIndexPage` 是栈顶时，设置 `OverlayManager().setMainTabsVisible(true)`。
- 当从首页 push 到任意二级页面时，`didPushNext` 设置为 false。
- 当从二级页返回首页时，`didPopNext` 设置为 true。
- `SCIndexPage.dispose` 设置为 false。
- `OverlayManager.addMessage(...)` 或 `_shouldDisplayMessage(...)` 对 `type = 6` 判断 `mainTabsVisible == true`，否则直接丢弃或不入队。

不推荐只用 `navigator.canPop()`：

- 可以作为兜底，但语义不够清晰。
- 登录页、启动页也可能是根页面，不能等同于首页四 Tab。

### 5.5 调整现有展示过滤

当前 `OverlayManager._shouldDisplayMessage(...)` 对 `type = 0 / 1 / 5` 做当前房间匹配：

```dart
if (message.type != 0 && message.type != 1 && message.type != 5) {
  return true;
}
...
return currentRoomId == messageRoomId;
```

新增 `type = 6` 时不要走当前房间匹配，而是走首页四 Tab 匹配：

- `type = 6`：只判断首页四 Tab 是否可见、全局飘屏开关是否开启、必要字段是否完整。
- `type = 0 / 1 / 5`：保留现有房间匹配，避免破坏当前房间内特效体验。
- `type = 2 / 3 / 4`：按现有逻辑评估是否也需要作用域限制，本需求不建议顺手改。

### 5.6 点击进房

新 Widget 点击继续复用：

```dart
SCRoomUtils.goRoom(
  message.roomId!,
  navigatorKey.currentState!.context,
  fromFloting: true,
);
```

现有 `SCRoomUtils.goRoom(...)` 已处理：

- 当前没有房间：弹确认后进房。
- 当前房间最小化且房间相同：打开当前房间。
- 当前已在其他房间：弹确认切房。

这里不需要新增路由能力。

## 6. 客户端兜底方案

如果后端暂时不能推送 `BIG_GIFT`，可以做临时客户端兜底，但不推荐作为长期方案。

临时做法：

- 在 `GiftPage._executeGiftRequest(...)` 普通礼物成功后判断：
  - `!request.isLuckyGiftRequest`
  - `giftTab` 不是 `LUCK / LUCKY_GIFT / MAGIC`
  - `gift.giftCandy * request.quantity >= threshold`
- 构造 `BigBroadcastGroupMessage("BIG_GIFT", SCFloatingMessage(...))`。
- 调用 `RtmProvider.sendBigBroadcastGroup(...)`。
- 必须只按一次送礼行为发送，不能放在 `sendGiftMsg(...)` 的 `acceptUsers` 循环里。

风险：

- 客户端可伪造全服广播，不够可信。
- 多端并发、弱网重试可能重复。
- 阈值和礼物类型判断容易与后端不一致。

因此正式方案仍建议后端推送。

## 7. 去重与队列策略

建议新增去重缓存：

- 位置：`RealTimeMessagingManager` 或 `OverlayManager`。
- 结构：`LinkedHashMap<String, int>`，保存最近 100 条 event key 和时间。
- TTL：30 秒到 60 秒。
- key 优先使用 `eventId`。

队列策略：

- 继续使用 `OverlayManager` 现有优先级队列。
- 大额礼物 `priority = 900`，低于幸运礼物大奖 `1000`。
- 可选：当队列过长时丢弃低优先级大额礼物，避免首页连续刷屏。

## 8. 开关策略

沿用现有全局飘屏开关：

- `SCGlobalConfig.isFloatingAnimationInGlobal`
- 本地持久化 key：`FloatingAnimationInGlobal`
- 低性能设备会通过 `clampVisualEffectPreference(...)` 关闭。

建议：

- 大额礼物全局飘窗受这个开关控制。
- 不受 `isGiftSpecialEffects` 控制，因为它是全屏礼物特效开关。
- 不受 `isLuckGiftSpecialEffects` 控制，因为本需求不是幸运礼物。

## 9. 验收用例

### 9.1 基础展示

- 用户 A 在房间 B 送普通礼物 C，总价值达到阈值。
- 当前用户在 `home`：看到顶部飘窗。
- 当前用户在 `explore`：看到顶部飘窗。
- 当前用户在 `message`：看到顶部飘窗。
- 当前用户在 `me`：看到顶部飘窗。

### 9.2 范围限制

- 当前用户在语音房页面：不展示该全局大额礼物飘窗。
- 当前用户在个人资料页、设置页、聊天详情页、充值页：不展示。
- App 在启动页或登录页：不展示。

### 9.3 礼物类型

- 普通礼物达到阈值：展示。
- 普通礼物未达到阈值：不展示。
- 幸运礼物或魔法礼物达到金额：不走 `BIG_GIFT`，继续走现有幸运礼物逻辑。
- 多人收礼的一次送礼：只展示一条。

### 9.4 点击进房

- 当前无房间：点击飘窗，确认后进入房间 B。
- 当前房间已最小化且是房间 B：点击后打开当前房间。
- 当前已在其他房间：点击后弹切房确认。
- `roomId` 为空或房间不存在：不展示或进房失败时走现有错误提示。

### 9.5 稳定性

- 连续多条大额礼物：按队列顺序展示，不重叠。
- 同一 `eventId` 重复到达：只展示一次。
- 左滑关闭后下一条能继续展示。
- 关闭全局飘屏开关后不展示。
- 低性能设备默认不展示。

## 10. 建议实施顺序

1. 和后端确认 `BIG_GIFT` 全服广播协议、阈值、是否包含 `roomName / giftName / giftPhoto / eventId`。
2. 新增 `SCBigGiftBroadcastPush` 模型和 `SCFloatingMessage` 扩展字段。
3. 新增 `FloatingBigGiftScreenWidget`，复用现有动画、点击、左滑行为。
4. `OverlayManager` 支持 `type = 6`，并新增首页四 Tab 可见性控制。
5. `SCIndexPage` 用 `RouteAware` 控制 `OverlayManager` 的主 Tab 展示作用域。
6. `RtmProvider._newBroadCastMsgRecv(...)` 接入 `BIG_GIFT`。
7. 加去重和队列上限保护。
8. 做手动验收与必要 Widget/单元测试。

## 11. 需要确认的问题

- 大额阈值最终是多少：沿用 `10000`，还是后端配置？
- 飘窗是否展示收礼人：当前需求文案不需要，只写“用户 A 在房间 B 送了 C 礼物”。
- 多目标送礼是否只展示一次：建议只展示一次。
- 如果发送者自己也在首页四 Tab，是否也展示自己刚送的大额礼物：建议展示，和全服广播一致；如产品不希望自显，需要后端或前端按 `sendUserId == currentUserId` 过滤。
- 房间 B 名称为空时的兜底文案：建议使用 `roomId` 或本地化的“语音房”。