# 语言房重构方案

## 文档目的

本文只记录一套可执行的重构方案，本轮不改业务代码。

本次建议的重构范围不是“整套语言房全部推倒重写”，而是优先重构**语言房特效子系统**，重点解决以下问题：

- 礼物特效、进场、飞向麦位、房间飘屏并发时主线程抢占严重
- 特效触发源分散，队列和调度分散，后续越优化越难维护
- 房间内特效偶发残留到首页/其它页面，生命周期边界不清晰
- 已做过多轮局部优化，但整体架构仍然偏重，继续打补丁收益会越来越低

本方案的核心原则是：

- 尽可能保留当前礼物业务逻辑、素材、阈值和视觉表现
- 先重构特效系统，不一次性推倒 `RTC/RTM/房间业务` 主链路
- 先做“收口与解耦”，再做“性能压测与降级”

---

## 当前建议结论

建议重构方向：

- 保留现有房间业务、消息协议、礼物配置接口和大部分现有素材
- 将当前分散在 `VoiceRoomPage / RTM / RTC / OverlayManager / SCGiftVapSvgaManager / GiftAnimationManager / RoomEntranceQueue` 的特效触发与播放逻辑，统一收口到一个**语言房特效引擎**
- 把“事件归一化、去重、合并、优先级、预算控制、播放调度、生命周期回收”集中管理

不建议本轮做的事：

- 不建议同时重写整套语言房 UI、聊天室、麦位、RTC 状态层
- 不建议先动后端协议
- 不建议一开始就更换全部动画素材格式

---

## 当前架构现状

### 当前核心模块

| 模块 | 当前文件 | 当前职责 | 当前问题 |
| --- | --- | --- | --- |
| 房间主页面 | `lib/modules/room/voice_room_page.dart` | 挂载房间 UI、礼物播报、进场动画、幸运礼物动画、飞向麦位控制器 | 页面层知道太多特效细节，既处理业务又处理动画 |
| 房间消息入口 | `lib/services/audio/rtm_manager.dart` | 处理群消息、礼物消息、进场消息、全服广播、飘屏 | 直接触发 `play()`、`OverlayManager().addMessage()`，事件与 UI 强耦合 |
| 房间状态入口 | `lib/services/audio/rtc_manager.dart` | 管理进房、退房、麦位、在线用户、房间状态 | 也会直接触发进场坐骑特效，和 RTM 形成双入口 |
| 全屏礼物播放器 | `lib/shared/tools/sc_gift_vap_svga_manager.dart` | 管理高成本 `VAP/SVGA` 全屏特效任务 | 只管理自己这一条链路，不是整个房间特效系统的总调度器 |
| 房间调度器 | `lib/shared/tools/sc_room_effect_scheduler.dart` | 在高成本特效期间延后部分低优先级特效 | 只有“延后”能力，没有统一队列、优先级、预算、去重、丢弃策略 |
| 顶部礼物播报条 | `lib/services/gift/gift_animation_manager.dart` + `lib/ui_kit/widgets/room/anim/l_gift_animal_view.dart` | 4 个槽位的礼物播报、连击合并、幸运礼物奖励框 | 已做局部优化，但仍独立存在，未纳入统一引擎 |
| 进场动画 | `lib/ui_kit/widgets/room/anim/room_entrance_screen.dart` | 房内横向 banner 进场队列 | 又是一套独立队列与独立状态机 |
| 飞向麦位 | `lib/ui_kit/widgets/room/anim/room_gift_seat_flight_overlay.dart` | 礼物图片从中间飞向目标麦位 | 独立 overlay、独立队列、独立缓存 |
| 飘屏 | `lib/shared/data_sources/sources/local/floating_screen_manager.dart` | 幸运礼物、礼物、火箭、红包、游戏飘屏 | 仍是独立优先队列，与房间特效生命周期分离 |
| 旧进场链路 | `lib/ui_kit/widgets/room/anim/room_entrance_widget.dart` | 旧版 `SVGA` 进场队列与 helper | 当前基本不承担主展示，但代码仍存在，增加维护噪音 |

### 当前核心问题

- 同一套语言房里同时存在多套特效队列和状态机
- `RTM/RTC` 直接知道“怎么播动画”，不是只产出事件
- 房间专属特效有一部分挂在根层 `MaterialApp builder`，不是挂在房间路由内部
- 同类事件存在本地触发与远端回流双路径，天然有重复触发风险
- 当前调度器只在高成本特效时“暂缓别的”，但底层仍是多个系统各播各的
- 历史链路未完全收口，例如旧进场 helper 仍保留

---

## 根因判断

当前卡顿的根因更偏向**结构性问题**，而不是单个控件或单次绘制的问题：

1. 多源头直接驱动 UI  
   `RTM/RTC/RoomPage/GiftSystem` 都可能直接触发动画。

2. 多条高频动画链路并发  
   全屏 `VAP/SVGA`、顶部礼物条、进场 banner、飞向麦位、房间飘屏可能同时争抢主线程。

3. 房间特效不是一个完整子系统  
   现在只有局部管理器，没有一个真正拥有“总入口、总队列、总预算、总生命周期”的 runtime。

4. 业务状态更新和特效播放距离太近  
   房间麦位刷新、在线用户刷新、消息列表更新，会和特效播放共享同一个页面状态环境。

5. 生命周期边界偏松  
   房间退出后，根层 overlay 和异步回调仍然需要额外兜底清理。

---

## 重构目标

### 目标

- 让语言房特效具备统一入口、统一调度、统一生命周期
- 在不改现有礼物业务口径的前提下降低并发卡顿
- 让房间特效只在房间内部存在，不再溢出到其它页面
- 让每种特效都可以独立限流、合并、降级、观测
- 让后续继续优化时，能在统一引擎层处理，而不是继续在各个页面打补丁

### 非目标

- 本轮不改变房间消息协议
- 本轮不重做礼物页面或礼物发送接口
- 本轮不调整礼物业务规则口径
- 本轮不强制替换所有动画素材格式

---

## 必须保留的当前礼物/进场业务逻辑

本次重构的前提是：**默认保留当前业务判断口径，只调整结构和调度层**。以下逻辑建议在首轮迁移中原样保留。

| 逻辑项 | 当前口径 | 重构策略 |
| --- | --- | --- |
| 礼物消息来源 | 继续沿用当前房间 RTM 自定义消息 | 保留，不改协议 |
| 全屏礼物触发口径 | 继续按 `gift.special + giftSourceUrl + scGiftHasFullScreenEffect(...)` 判定 | 保留，先抽到策略层 |
| 礼物特效总开关 | 继续沿用 `SCGlobalConfig.isGiftSpecialEffects` | 保留，接入新引擎策略层 |
| 入场坐骑开关 | 继续沿用 `SCGlobalConfig.isEntryVehicleAnimation` | 保留，接入新引擎策略层 |
| 飘屏开关 | 继续沿用 `SCGlobalConfig.isFloatingAnimationInGlobal` | 保留，接入新引擎策略层 |
| 顶部礼物播报条合并规则 | 继续按当前 `labelId` 逻辑合并活动项和待播项 | 保留，迁移时保持视觉与合并口径一致 |
| 顶部礼物播报条槽位数 | 继续保持 `4` 个槽位 | 保留，首轮不改 |
| 顶部礼物播报待播上限 | 继续保持当前上限 `24` | 保留，后续再参数化 |
| 顶部礼物播报空闲消失时间 | 继续保持约 `3200ms` | 保留，后续再参数化 |
| `customAnimationCount` 逻辑 | 继续作为飞向麦位次数和礼物数量步进动画的依据 | 保留，不改视觉节奏 |
| 飞向麦位目标解析 | 继续按当前 `toUser -> account -> 麦位映射` 解析目标 | 保留，迁移时统一封装 |
| 飞向麦位会话去重 | 继续保留当前 `queueTag / sessionKey` 级别清理策略 | 保留 |
| 幸运礼物里程碑特效 | 继续保留当前里程碑资源集合与触发口径 | 保留 |
| 幸运礼物顶部奖励框 | 继续保留当前奖励金额展示方式 | 保留 |
| 幸运礼物 burst 条件 | 继续保持“倍率 `>= 10x` 或单次奖励 `> 5000`” | 保留 |
| 幸运礼物飘屏口径 | 继续保持当前服务端 `globalNews` + 倍率门槛逻辑 | 保留 |
| 大额礼物房间飘屏阈值 | 继续保持当前 `coins > 9999` 才触发房间礼物飘屏 | 保留 |
| 礼物触发麦位刷新 | 继续保留礼物触发后的节流刷新逻辑 | 保留，迁移时挪到 effect bridge 或 event side-effect 层 |
| 房间进场横幅 | 继续保留当前房内进场 banner 表达方式 | 保留视觉，不一定保留旧实现 |

### 建议保留但从硬编码改为配置化的参数

- 礼物播报槽位数
- 礼物播报待播上限
- 进场队列上限
- 飞向麦位单会话上限
- 高成本特效队列上限
- 飘屏丢弃阈值
- 各类优先级与独占关系

---

## 目标架构

### 架构总览

```mermaid
graph TD
    A[RTM/RTC/房间本地动作] --> B[RoomEffectEventAdapter]
    B --> C[RoomEffectEngine]
    C --> D[EffectPolicy]
    C --> E[Dedup & Merge]
    C --> F[Lane Dispatcher]
    F --> G[Fullscreen Lane]
    F --> H[Entrance Lane]
    F --> I[GiftTicker Lane]
    F --> J[SeatFlight Lane]
    F --> K[Floating Lane]
    G --> L[RoomEffectStage]
    H --> L
    I --> L
    J --> L
    K --> L
    L --> M[SVGA/VAP/Image/Implicit Animations]
    C --> N[Metrics & Trace]
```

### 核心思想

- 所有原始事件先进入 `RoomEffectEventAdapter`
- adapter 只负责把“原始 RTM/RTC/本地动作”变成**标准化特效事件**
- 所有标准化事件再进入 `RoomEffectEngine`
- engine 统一做去重、合并、优先级排序、预算判断、降级和分 lane 调度
- 真正的渲染层只负责展示，不再关心业务来源

---

## 推荐模块拆分图

建议新增一个独立的语言房特效模块，命名可为 `lib/modules/room_effect/` 或 `lib/shared/room_effect/`。

```text
lib/
  modules/
    room_effect/
      domain/
        room_effect_event.dart
        room_effect_task.dart
        room_effect_lane.dart
        room_effect_priority.dart
        room_effect_policy_snapshot.dart
      application/
        room_effect_event_adapter.dart
        room_effect_engine.dart
        room_effect_deduplicator.dart
        room_effect_merger.dart
        room_effect_policy.dart
        room_effect_metrics.dart
      presentation/
        room_effect_stage.dart
        layers/
          room_fullscreen_effect_layer.dart
          room_entrance_effect_layer.dart
          room_gift_ticker_layer.dart
          room_seat_flight_layer.dart
          room_floating_effect_layer.dart
      infrastructure/
        room_effect_asset_preloader.dart
        room_effect_player_bridge.dart
        room_effect_lifecycle_guard.dart
```

### 各模块职责

| 模块 | 职责 | 说明 |
| --- | --- | --- |
| `RoomEffectEventAdapter` | 事件归一化 | 把 `RTM/RTC/RoomPage` 的原始数据转为统一事件对象 |
| `RoomEffectEngine` | 统一调度核心 | 做入队、去重、合并、优先级、预算、丢弃、lane 分发 |
| `RoomEffectPolicy` | 播放策略 | 根据机型、开关、 backlog、当前播放状态决定播什么、延后什么、降级什么 |
| `RoomEffectStage` | 页面内特效承载层 | 只在语言房路由内部挂载，房间退出就一并销毁 |
| `PlayerBridge` | 播放器桥接层 | 首轮复用现有 `SCGiftVapSvgaManager` / `GiftAnimationManager` / 现有动画组件 |
| `AssetPreloader` | 资源预热 | 统一预热图片、SVGA、VAP，本轮不再让每个特效组件各自处理 |
| `Metrics` | 指标与日志 | 记录入队数、丢弃数、等待时长、播放耗时、异常和 backlog |

---

## 目标事件模型

建议统一定义一个标准化事件对象 `RoomEffectEvent`，至少包含以下信息：

- `eventId`
- `roomId`
- `eventType`
- `source`
- `createdAt`
- `priority`
- `dedupKey`
- `mergeKey`
- `userId`
- `targetUserId`
- `giftId`
- `payload`
- `requiresHeavyRenderer`
- `roomScoped`

### 推荐事件类型

- `roomUserJoin`
- `roomMountEntrance`
- `giftTicker`
- `giftFullscreen`
- `giftSeatFlight`
- `giftFloating`
- `luckyGiftMilestone`
- `luckyGiftRewardTicker`
- `luckyGiftBurst`
- `rocketFloating`
- `redPacketFloating`
- `gameFloating`

### 为什么要有标准化事件层

- 后续所有去重和合并都建立在统一事件模型上
- 可把“同一礼物事件触发 3 种视觉表现”拆成 3 个子任务，而不是让 RTM 直接调用 3 个 UI 系统
- 可支持本地自发事件和远端回流事件的统一去重

---

## 目标任务模型

事件进入引擎后，不直接播放，而是先变成 `RoomEffectTask`。

一个 task 建议至少包含：

- `taskId`
- `lane`
- `priority`
- `enqueueAt`
- `deadline`
- `exclusive`
- `mergeable`
- `mergeKey`
- `dropPolicy`
- `payload`
- `onStart`
- `onComplete`
- `onCancel`

### 推荐的 lane 划分

| Lane | 作用 | 特点 |
| --- | --- | --- |
| `fullscreen` | 全屏礼物、幸运礼物 burst、进场坐骑等高成本特效 | 可独占，优先级最高 |
| `entrance` | 房间进场 banner | 串行，可合并，可被延后 |
| `giftTicker` | 顶部礼物播报条 | 维持 4 槽位模型 |
| `seatFlight` | 飞向麦位 | 可批量、可会话级去重 |
| `floating` | 房间飘屏、幸运礼物飘屏、火箭、红包、游戏 | 可按消息类型和房间范围过滤 |

---

## 页面挂载方式调整

### 当前问题

当前房间特效有一部分挂在根层 `MaterialApp builder`，例如：

- 全屏 `VapPlusSvgaPlayer`
- `RoomGiftSeatFlightOverlay`

这意味着：

- 特效承载层不完全属于房间页面
- 房间退出后需要额外兜底清理
- 根层 overlay 容易被误复用到非房间页面

### 目标方式

推荐新增 `RoomEffectStage`，只挂在语言房页面内：

```mermaid
graph TD
    A[VoiceRoomPage] --> B[RoomScene]
    A --> C[RoomEffectStage]
    C --> D[Fullscreen Layer]
    C --> E[Entrance Layer]
    C --> F[GiftTicker Layer]
    C --> G[SeatFlight Layer]
    C --> H[Floating Layer]
```

### 结果

- 房间特效生命周期跟随 `VoiceRoomPage`
- 退房、最小化、切房时统一收口
- 根层只保留真正全局的东西，房间特效不再越界

---

## 首轮推荐复用现有实现的方式

为尽量保留当前礼物逻辑，首轮不需要把所有 renderer 重写，可以先“新引擎 + 旧 renderer”。

### 可复用项

| 现有实现 | 首轮建议 |
| --- | --- |
| `SCGiftVapSvgaManager` | 作为 `fullscreen lane` 的底层播放器桥接 |
| `GiftAnimationManager` | 作为 `giftTicker lane` 的底层 4 槽位实现 |
| `RoomGiftSeatFlightOverlay` | 作为 `seatFlight lane` 的底层渲染器 |
| `RoomAnimationQueueScreen` | 其视觉可复用，但队列控制迁到新引擎 |
| `OverlayManager` | 首轮可继续承载非房间全局类型；房间类型逐步迁出 |

### 不建议继续保留为长期方案的实现

| 现有实现 | 建议 |
| --- | --- |
| `room_entrance_widget.dart` 的旧 helper/queue | 清理掉，不再作为正式链路 |
| 在 `RTM/RTC` 中直接 `play()` 或 `addMessage()` | 改为统一投递特效事件 |
| 在根层 `MaterialApp builder` 挂房间专属特效层 | 迁回房间路由内部 |

---

## 调度与降级策略

### 首轮策略

首轮重构不建议改业务口径，但建议统一调度策略。

#### 建议规则

- `fullscreen lane` 播放时，`entrance / floating / seatFlight` 默认延后
- `giftTicker lane` 继续独立展示，但只保留当前 4 槽位，不无限堆积
- `seatFlight lane` 保持当前 `customAnimationCount` 逻辑，但由引擎统一裁剪上限
- `entrance lane` 超过 backlog 后可合并为“X 人进入房间”
- `floating lane` 在高峰时优先保留高优先级类型，低优先级直接丢弃

### 第二阶段可再加的自适应策略

- backlog 超阈值时，把同礼物多次飞向麦位降成 1 次飞行 + 数量角标
- 进场队列过长时，多条普通进场合并成一条摘要
- 同时存在全屏高成本特效时，房间礼物飘屏暂停或只保留 1 条
- 低性能设备继续保留现有总开关，但高性能设备也可按瞬时 backlog 动态降级

---

## 迁移顺序

建议按“先收口入口，再迁移渲染，再清理历史代码”的顺序做，避免一口气全动。

### 阶段 0：建立基线与指标

目标：

- 先补齐特效侧可观测性
- 固化当前礼物逻辑和关键参数，形成“迁移不改口径”的基线

本阶段内容：

- 统计每类特效的入队数、丢弃数、平均等待时长、播放时长
- 统计 `fullscreen/entrance/giftTicker/seatFlight/floating` 的 backlog 峰值
- 用 `FrameTiming` 记录语言房高压场景的 build/raster 情况

本阶段不改：

- 不改现有播放逻辑
- 不改现有视觉
- 不改现有业务阈值

### 阶段 1：统一事件入口

目标：

- 引入 `RoomEffectEventAdapter`
- 所有房间特效先变成统一事件对象

本阶段内容：

- 把 `RTM/RTC/VoiceRoomPage/GiftSystem` 里直接触发特效的地方改为“投递事件”
- 本地触发与远端回流先统一走一层去重 key

本阶段不改：

- renderer 先不迁
- `SCGiftVapSvgaManager`、`GiftAnimationManager` 等先照旧使用

关键收益：

- 从这一阶段开始，特效来源就被收口了

### 阶段 2：落地 `RoomEffectEngine`

目标：

- 让所有统一事件进入引擎
- 引擎接管优先级、去重、合并和 lane 分发

本阶段内容：

- 新建 `RoomEffectEngine`
- 新建 lane 模型
- 先做不改变视觉的“旧 renderer 包装”

本阶段不改：

- 不改具体动画 UI
- 不改素材

关键收益：

- 从“多套队列系统”变成“一个总引擎 + 多条 lane”

### 阶段 3：把房间特效挂回房间路由内部

目标：

- 新建 `RoomEffectStage`
- 把房间专属层从根层迁回 `VoiceRoomPage`

本阶段内容：

- `RoomEffectStage` 承载房间内所有特效 layer
- 根层只保留真正全局的内容
- 统一退房清理、最小化清理、切房清理

本阶段重点回归：

- 房间退出后不再有礼物图残留
- 房间飘屏不再跑到首页

### 阶段 4：迁移 `fullscreen lane`

目标：

- 先把最高成本、影响最大的特效链路收口

本阶段内容：

- `SCGiftVapSvgaManager` 改为由 `fullscreen lane` 调用
- 进场坐骑、全屏礼物、幸运礼物 burst 都走统一 lane
- 自带独占、优先级和预热策略

本阶段必须保持不变：

- 当前全屏礼物触发口径不变
- 当前幸运礼物里程碑和 burst 口径不变

### 阶段 5：迁移 `entrance lane`

目标：

- 收口房间进场 banner
- 清理旧进场链路

本阶段内容：

- `RoomAnimationQueueScreen` 只保留渲染，队列逻辑迁到 `entrance lane`
- 清理 `room_entrance_widget.dart` 旧 helper 及残余引用
- 引入本地与远端进场事件去重

本阶段必须保持不变：

- 当前进场 UI 表达不变
- 当前入场后坐骑与横幅仍可共存，但由统一引擎调度

### 阶段 6：迁移 `giftTicker lane`

目标：

- 保留当前 4 槽位礼物播报条逻辑，但把队列和状态收回引擎

本阶段内容：

- `GiftAnimationManager` 改为 lane 内 renderer bridge
- 继续保留当前 `labelId` 合并、4 槽位、空闲消失时间、数量步进动画
- 幸运礼物奖励框仍保留当前样式

本阶段必须保持不变：

- 连击合并口径
- `customAnimationCount` 对数量展示的影响
- 幸运礼物奖励框逻辑

### 阶段 7：迁移 `seatFlight lane`

目标：

- 把飞向麦位从独立控制器改为统一 lane 管理

本阶段内容：

- 复用现有 `RoomGiftSeatFlightOverlay` 作为渲染层
- `queueTag/sessionKey` 的批量裁剪和清理迁入 engine
- 目标麦位 key 解析改成统一桥接

本阶段必须保持不变：

- 当前会话级去重逻辑
- 当前 `customAnimationCount` 粒度
- 当前图片预热行为

### 阶段 8：迁移 `floating lane`

目标：

- 收口房间礼物飘屏、幸运礼物飘屏、火箭、红包、游戏飘屏

本阶段内容：

- 房间内的 floating 类型全部走 `floating lane`
- 真正全局广播的类型与房间类型分开
- `OverlayManager` 只保留全局用法，房间类型从中剥离

本阶段必须保持不变：

- 幸运礼物 `globalNews` 逻辑不变
- 房间礼物 `coins > 9999` 才飘屏的逻辑不变

### 阶段 9：清理历史实现与补充自适应降级

目标：

- 删掉双轨实现
- 把当前“局部优化痕迹”收成统一结构

本阶段内容：

- 删除旧进场 helper
- 删除 `RTM/RTC` 中直接 `play()` 和 `addMessage()` 的旧入口
- 完成 backlog 降级策略与观测面板

---

## 关键兼容策略

### 1. 先换“控制面”，不先换“渲染面”

首轮不要把所有动画组件重写掉。

推荐策略：

- 新引擎先接管“什么时候播、播哪条、谁先谁后、是否丢弃”
- 旧组件先继续负责“怎么画出来”

这样做的好处：

- 视觉回归风险小
- 礼物逻辑更容易保持一致
- 每一阶段都可以独立回滚

### 2. 消息协议不动

当前房间消息、礼物消息、幸运礼物消息结构先不改。

这样可以：

- 避免前后端联动阻塞
- 避免把“性能问题”变成“协议问题”

### 3. 参数冻结后再迁移

建议先把以下参数冻结成一份配置文档或常量表：

- 幸运礼物里程碑列表
- 幸运礼物 burst 条件
- 房间礼物飘屏阈值
- 顶部礼物播报条槽位与时长
- 飞向麦位上限
- 进场队列上限

这样迁移时只改结构，不改结果。

---

## 风险点列表

| 风险点 | 说明 | 风险等级 | 缓解方式 |
| --- | --- | --- | --- |
| 本地事件与远端回流重复 | 自己送礼、自己进房、进场坐骑等容易双触发 | 高 | 引入 `dedupKey`，按 `roomId + type + sender + target + gift + timeWindow` 去重 |
| 去重过度导致特效漏播 | 某些高频连击若 key 设计过粗，会把应播事件吃掉 | 高 | 区分 `dedupKey` 和 `mergeKey`，先留日志，初期采用保守去重 |
| 房间退出后仍有旧特效回调 | `postFrame / delayed / timer / precache` 都可能晚到 | 高 | 所有 task 和 layer 引入 `sessionToken` 或 `roomLifecycleToken` 校验 |
| 渲染层迁移后层级错乱 | 根层迁到房间层后，z-order 可能改变 | 中 | 在 `RoomEffectStage` 中明确 layer 顺序，先对齐现有视觉层级 |
| 资源预热过多导致内存抖动 | 统一预热后若没有预算控制，容易顶高内存 | 中 | 按 lane、资源类型、尺寸做分层缓存和 LRU |
| 幸运礼物口径漂移 | 这块逻辑复杂，回归风险高 | 高 | 首轮冻结参数与触发口径，不做业务变更 |
| 飞向麦位目标丢失 | 目标座位 GlobalKey 尚未可用时可能丢动画 | 中 | 保留当前重试机制，但统一纳入 lane，限制重试次数 |
| 飘屏房间范围判断错误 | 房间飘屏与全局飘屏容易混 | 中 | 明确 `roomScoped` 与 `globalScoped` 两类事件 |
| 迁移阶段代码并存时间过长 | 双轨逻辑存在越久，后续越难收口 | 中 | 每一阶段都指定“完成后可删”的旧文件或旧入口 |
| 测试面过大 | 礼物、幸运礼物、火箭、红包、进场、坐骑交叉很多 | 高 | 用阶段化回归清单，按 lane 逐项验收 |

---

## 回归测试清单

### 礼物链路

- 单次送礼 1 次
- 同一礼物连续送 5 次、10 次
- `customAnimationCount > 1` 的批量场景
- 幸运礼物普通中奖
- 幸运礼物高倍率中奖
- 同时出现全屏礼物 + 顶部播报条 + 飞向麦位

### 进场链路

- 自己进入房间
- 别人进入房间
- 别人带坐骑进入房间
- 同时 5 人以上快速进入

### 飘屏链路

- 房间礼物飘屏
- 幸运礼物房间飘屏
- 全局广播幸运礼物飘屏
- 火箭飘屏
- 红包飘屏

### 生命周期

- 房间内最小化
- 退出房间
- 切到首页/消息/我的
- 从 A 房切到 B 房

### 性能

- 普通机型连续送礼 10 秒
- 低性能机型连续送礼 10 秒
- 进场和礼物叠加压测
- 房间内停留 10 分钟观察缓存与内存变化

---

## 验收指标建议

建议在重构过程中记录以下指标，避免“感觉快了”但没有客观标准：

- 语言房高压场景下 `FrameTiming` 的 `build/raster` P95
- `fullscreen lane` 平均等待时长
- `entrance/floating/seatFlight` backlog 峰值
- 被丢弃任务数量和占比
- 同事件重复触发数
- 房间退出后残留特效数

### 目标方向

- 房间高压场景下明显减少整页卡顿和掉帧
- 不再出现房间特效溢出到首页
- 不再依赖在多个管理器里各自补清理逻辑
- 新增一个特效类型时，只需要走“标准化事件 -> lane -> layer”链路

---

## 预计实施节奏

如果只重构语言房特效子系统，不推倒整套房间业务，建议节奏如下：

| 阶段 | 预估工作量 |
| --- | --- |
| 阶段 0 ~ 2 | 2 到 3 天 |
| 阶段 3 ~ 5 | 4 到 6 天 |
| 阶段 6 ~ 8 | 4 到 6 天 |
| 阶段 9 与回归 | 2 到 3 天 |

整体建议：

- 保守估计约 `2` 周
- 如果中途顺手一起重构 `RTC/RTM/RoomPage` 主业务结构，工期会明显变长

---

## 多线程并行执行方案

如果后续不是单线程顺着做，而是你准备把这次重构拆成多个并行线程分别跑，建议采用**“3 个主线程并行 + 1 个收尾线程串行收口”**的方案。

### 并行收益预估

按“最稳的预期”估算：

- 单线程完整落地：约 `20 到 24` 小时
- 多线程并行后：约 `14 到 16` 小时

这里的前提是：

- 先冻结接口命名和模块边界
- 尽量避免多个线程同时改同一批现有文件
- 最后仍保留一个统一收尾和回归线程

不建议的并行方式：

- 不建议 3 个线程同时直接改 `rtm_manager.dart / rtc_manager.dart / voice_room_page.dart`
- 不建议一边改 engine，一边让多个线程各自发明自己的事件模型
- 不建议一开始就多个线程同时删旧链路

### 并行原则

1. 先统一接口，再并行开发  
   至少先约定好以下对象名和职责：

   - `RoomEffectEvent`
   - `RoomEffectTask`
   - `RoomEffectLane`
   - `RoomEffectEngine`
   - `RoomEffectStage`
   - `RoomEffectEventAdapter`

2. 新文件优先并行，旧文件尽量收口到单一线程  
   新增模块最适合多线程拆分；旧有入口文件应尽量减少多人同时修改。

3. 先搭骨架，再接现有链路  
   先让 engine 与 stage 的框架稳定，再开始把 `RTM/RTC/VoiceRoomPage` 接上去。

4. 收尾一定要串行  
   旧链路删除、层级调整、房间生命周期回收、回归修 bug，这些必须收口到最后一个线程统一处理。

---

### 推荐线程划分

#### 线程 A：Engine 基础层

定位：

- 负责“语言房特效引擎”的核心模型与调度骨架

推荐负责范围：

- `lib/modules/room_effect/domain/`
- `lib/modules/room_effect/application/`
- `lib/modules/room_effect/infrastructure/` 中和调度、预热、生命周期守卫相关的文件

推荐文件所有权：

- `room_effect_event.dart`
- `room_effect_task.dart`
- `room_effect_lane.dart`
- `room_effect_priority.dart`
- `room_effect_engine.dart`
- `room_effect_policy.dart`
- `room_effect_deduplicator.dart`
- `room_effect_merger.dart`
- `room_effect_metrics.dart`
- `room_effect_asset_preloader.dart`
- `room_effect_lifecycle_guard.dart`

本线程不建议碰：

- `rtm_manager.dart`
- `rtc_manager.dart`
- `voice_room_page.dart`
- 现有具体动画 widget 的渲染实现

本线程交付物：

- 可编译的 engine/domain/application 基础骨架
- lane、task、event、policy 的统一接口
- 基本的 backlog、优先级、去重、合并接口

#### 线程 B：Stage 与渲染承载层

定位：

- 负责“语言房特效舞台”和各 layer 的承载结构

推荐负责范围：

- `lib/modules/room_effect/presentation/`

推荐文件所有权：

- `room_effect_stage.dart`
- `layers/room_fullscreen_effect_layer.dart`
- `layers/room_entrance_effect_layer.dart`
- `layers/room_gift_ticker_layer.dart`
- `layers/room_seat_flight_layer.dart`
- `layers/room_floating_effect_layer.dart`
- 如果需要，可新增 presentation 侧 controller 或 snapshot 文件

本线程可复用但不建议大改的旧文件：

- `lib/ui_kit/widgets/room/anim/l_gift_animal_view.dart`
- `lib/ui_kit/widgets/room/anim/room_entrance_screen.dart`
- `lib/ui_kit/widgets/room/anim/room_gift_seat_flight_overlay.dart`
- `lib/ui_kit/widgets/room/effect/vapp_svga_layer_widget.dart`

建议策略：

- 先做 layer 容器和接口桥接，不先重写底层动画实现
- 首轮允许通过 bridge 调现有 renderer

本线程不建议碰：

- `rtm_manager.dart`
- `rtc_manager.dart`
- `main.dart`

本线程交付物：

- `RoomEffectStage`
- 各特效 layer 的挂载顺序和层级
- 渲染层与 engine 的消费接口

#### 线程 C：旧链路入口收口与适配层

定位：

- 负责把现有 `RTM/RTC/VoiceRoomPage/GiftSystem` 的特效触发点统一改成事件投递

推荐负责范围：

- `lib/services/audio/rtm_manager.dart`
- `lib/services/audio/rtc_manager.dart`
- `lib/modules/room/voice_room_page.dart`
- `lib/services/gift/gift_system_manager.dart`
- 适配层文件，例如：
  - `lib/modules/room_effect/application/room_effect_event_adapter.dart`
  - 或单独的 bridge/wiring 文件

本线程重点任务：

- 找出所有直接 `play()`、`OverlayManager().addMessage()`、直接入队的触发点
- 改为投递标准化事件
- 做本地触发和远端回流的去重 key
- 保持现有礼物业务逻辑不变

本线程不建议碰：

- `RoomEffectStage` 内部结构
- 各 layer 的视觉实现
- 大量历史文件删除

本线程交付物：

- 统一事件入口
- `RTM/RTC` 不再直接知道“怎么播动画”
- 旧业务逻辑已迁到 adapter/event 侧表达

#### 线程 D：收尾、清理与回归

定位：

- 在 A/B/C 合并后串行执行，不建议一开始就启动

推荐负责范围：

- `lib/main.dart`
- `lib/modules/room/voice_room_page.dart`
- `lib/shared/data_sources/sources/local/floating_screen_manager.dart`
- `lib/shared/tools/sc_room_effect_scheduler.dart`
- `lib/ui_kit/widgets/room/anim/room_entrance_widget.dart`
- 其它需要删除旧逻辑、改挂载层级、补回归日志的文件

本线程重点任务：

- 把房间专属特效层从根层尽量收回房间页内部
- 清理旧进场 helper 和双轨实现
- 清理失效入口
- 跑一轮回归，修明显联调问题

---

### 最稳的执行顺序

推荐按下面顺序跑，而不是 4 个线程同时无序开工。

#### 第 1 步：接口冻结

由任意一个线程先完成，建议控制在 `0.5 到 1` 小时内。

需要先冻结的内容：

- `RoomEffectEvent` 字段
- `RoomEffectTask` 字段
- lane 列表
- engine 对外接口
- stage 对外接口
- adapter 的输入输出职责

这一步完成后，线程 A/B/C 才正式并行。

#### 第 2 步：A/B/C 三线程并行

并行期间建议这样分：

- A 只写 engine/domain/application 基础层
- B 只写 stage/presentation/layer 容器
- C 只写现有旧入口收口和事件适配

并行期间禁止多人同时改的文件：

- `lib/services/audio/rtm_manager.dart`
- `lib/services/audio/rtc_manager.dart`
- `lib/modules/room/voice_room_page.dart`
- `lib/main.dart`

这些文件建议默认归线程 C 或线程 D 所有。

#### 第 3 步：先合 A，再合 B，再合 C

推荐合并顺序：

1. 先合线程 A  
   先把 engine 和模型定住，避免后续接口继续漂。

2. 再合线程 B  
   让 stage 和 layer 按 A 的接口接上。

3. 再合线程 C  
   最后把现有旧入口真正接到 engine 上。

这样做的原因：

- 可以最大程度减少 `A/B/C` 三方接口对撞
- 让旧链路接入时面对的是已经稳定的 engine 与 stage

#### 第 4 步：最后由线程 D 串行收尾

线程 D 再做这些事：

- 根层与房间层的挂载调整
- 删除旧实现
- 生命周期清理
- 房间退出和切房回归
- backlog 观测和简单日志补充

---

### 推荐的文件写入边界

为了减少合并冲突，建议严格遵守下面的写入边界。

| 线程 | 允许重点修改 | 尽量不要修改 |
| --- | --- | --- |
| A | `lib/modules/room_effect/domain/`、`application/`、`infrastructure/` 新文件 | 现有房间业务文件 |
| B | `lib/modules/room_effect/presentation/` 新文件 | `rtm_manager.dart`、`rtc_manager.dart` |
| C | `rtm_manager.dart`、`rtc_manager.dart`、`voice_room_page.dart`、`gift_system_manager.dart`、adapter | `main.dart`、presentation 新文件的大结构 |
| D | `main.dart`、旧 helper 清理、根层挂载调整、遗留逻辑删除 | engine 核心接口 |

---

### 推荐的并行里程碑

建议把并行执行拆成 4 个里程碑，每个里程碑都要求能单独检查。

#### 里程碑 1

- A：engine/domain/task/lane 骨架完成
- B：stage/layer 容器骨架完成
- C：梳理所有旧触发点，列出事件映射表

#### 里程碑 2

- A：lane 调度、去重、合并接口可用
- B：各 layer 能消费统一 task 或 snapshot
- C：`RTM/RTC/VoiceRoomPage` 已改成先投递事件，不直接触发动画

#### 里程碑 3

- A/B：engine 与 stage 已能联通
- C：主要礼物/进场/飘屏入口已接新引擎

#### 里程碑 4

- D：旧链路清理、房间退出/切房回归完成

---

### 不同并行强度的建议

#### 最稳方案

- `3` 个主线程并行
- `1` 个收尾线程后置串行

适用场景：

- 你希望尽量减少互相撞车
- 你更在意一次性落稳，而不是追求最短墙钟时间

#### 更激进方案

- `4` 个线程一开始就并行

不太建议，原因是：

- `main.dart`
- `voice_room_page.dart`
- `rtm_manager.dart`
- `rtc_manager.dart`

这些文件很容易形成高冲突区，激进并行最后未必更快。

---

### 最终建议的并行执行口径

如果你后面准备“分别跑”多个线程，建议直接按下面口径执行：

- 线程 A：只做 engine/domain/application 基础层
- 线程 B：只做 stage/presentation/layer 承载层
- 线程 C：只做旧入口收口和事件适配
- 线程 D：最后统一清理旧链路、改挂载、跑回归

这是这次语言房特效系统重构里，**最稳、最不容易互相打架**的一种并行拆法。

---

## 可直接投喂 Codex 的执行 Prompts

下面这组 prompt 是给你后面开多个 Codex 线程时直接复制使用的。

推荐使用方式：

1. 先把“公共约定 prompt”复制给每个线程
2. 再把对应线程的专属 prompt 追加给该线程
3. 线程 D 不要一开始就跑，等 A/B/C 合并后再启动

### 公共约定 Prompt

建议把下面这段先发给每一个线程，作为共同上下文。

```text
你现在在 /Users/nigger/Documents/GitHub/chatapp3-flutter 仓库中工作。

当前目标不是重构整个语言房，而是优先重构“语言房特效子系统”。
请先阅读根目录文档：
- /Users/nigger/Documents/GitHub/chatapp3-flutter/语言房重构.md

本轮必须遵守这些硬约束：

1. 尽量保留当前礼物业务逻辑、阈值和视觉表现，不要擅自改业务口径。
2. 不要改房间消息协议，不要改后端接口。
3. 只在你被授权的写入范围内改文件，不要碰其它线程的主要负责文件。
4. 不要大规模格式化无关文件，不要顺手重构无关模块。
5. 如果你发现某个接口命名需要和其它线程统一，请优先遵守本文档中的统一命名，不要自行发明第二套。

统一命名约定如下：

- RoomEffectEvent
- RoomEffectTask
- RoomEffectLane
- RoomEffectPriority
- RoomEffectEngine
- RoomEffectPolicy
- RoomEffectEventAdapter
- RoomEffectStage

统一 lane 命名如下：

- fullscreen
- entrance
- giftTicker
- seatFlight
- floating

必须保留的当前关键逻辑：

- 顶部礼物播报条继续保持 4 个槽位
- 顶部礼物播报条待播上限继续按当前 24 处理
- 顶部礼物播报条空闲消失时长继续保持约 3200ms
- 飞向麦位继续保留 customAnimationCount 的粒度逻辑
- 幸运礼物 burst 继续保持“倍率 >= 10x 或单次奖励 > 5000”
- 房间礼物飘屏继续保持 coins > 9999 才触发
- 继续沿用当前特效总开关：
  - SCGlobalConfig.isGiftSpecialEffects
  - SCGlobalConfig.isEntryVehicleAnimation
  - SCGlobalConfig.isFloatingAnimationInGlobal

完成后请在回复中明确给出：

- 改了哪些文件
- 你负责范围内已经完成了什么
- 还依赖其它线程提供什么
- 有没有你刻意没有动的风险点
```

---

### 线程 A Prompt

用途：

- 负责 engine/domain/application 基础层

直接投喂：

```text
在遵守“公共约定 prompt”的前提下，执行线程 A 的任务。

你的职责是：搭建语言房特效系统的 engine/domain/application 基础层，只负责新架构骨架，不接老的 RTM/RTC 入口，不改现有房间业务触发逻辑。

你的主要目标：

1. 新增语言房特效模块基础目录，优先建议放在：
   - lib/modules/room_effect/domain/
   - lib/modules/room_effect/application/
   - lib/modules/room_effect/infrastructure/

2. 建立并实现以下核心对象或等价对象：
   - RoomEffectEvent
   - RoomEffectTask
   - RoomEffectLane
   - RoomEffectPriority
   - RoomEffectPolicy
   - RoomEffectEngine
   - RoomEffectDeduplicator
   - RoomEffectMerger
   - RoomEffectMetrics
   - RoomEffectLifecycleGuard
   - RoomEffectAssetPreloader

3. engine 至少要具备这些能力：
   - 接收 RoomEffectEvent
   - 转换为 RoomEffectTask
   - 按 lane 分发
   - 基于 priority 排序
   - 留出去重、合并、丢弃、延后、独占的接口
   - 能产出每个 lane 的可消费状态或流

4. 你可以先做“最小可用骨架”，但不要只写空壳文件。至少保证接口能表达真实系统能力。

5. 你需要把这些现有业务约束沉淀到 policy 或 constants 中，但不要改业务阈值：
   - giftTicker 4 槽位
   - pending 24
   - idle dismiss 3200ms
   - burst 条件
   - 飘屏阈值

你的明确写入范围：

- 可以新增和修改：
  - lib/modules/room_effect/domain/**
  - lib/modules/room_effect/application/**
  - lib/modules/room_effect/infrastructure/**

你的禁止写入范围：

- 不要修改：
  - lib/services/audio/rtm_manager.dart
  - lib/services/audio/rtc_manager.dart
  - lib/modules/room/voice_room_page.dart
  - lib/main.dart
  - lib/ui_kit/widgets/room/** 的现有渲染文件

你的产出要求：

- 代码必须可编译到“接口层面合理”
- 保持命名稳定，方便线程 B/C 对接
- 在最终回复里列出你定义的关键接口签名和文件列表
```

---

### 线程 B Prompt

用途：

- 负责 `RoomEffectStage` 和 presentation/layer 承载层

直接投喂：

```text
在遵守“公共约定 prompt”的前提下，执行线程 B 的任务。

你的职责是：搭建语言房特效系统的 presentation/stage/layer 承载层，重点是把房间内特效层级和挂载方式结构化，但不要改旧的 RTM/RTC 入口文件。

你的主要目标：

1. 新增 presentation 模块，优先建议放在：
   - lib/modules/room_effect/presentation/
   - lib/modules/room_effect/presentation/layers/

2. 建立并实现以下对象或等价对象：
   - RoomEffectStage
   - RoomFullscreenEffectLayer
   - RoomEntranceEffectLayer
   - RoomGiftTickerEffectLayer
   - RoomSeatFlightEffectLayer
   - RoomFloatingEffectLayer

3. 你的核心任务不是重写所有动画，而是先把“承载层和消费接口”搭好。首轮允许通过 bridge 复用现有 renderer。

4. 你需要明确 layer 的顺序和职责，建议至少能表达：
   - fullscreen 层
   - entrance 层
   - giftTicker 层
   - seatFlight 层
   - floating 层

5. 你可以为每个 layer 设计最小消费接口，例如：
   - 接收 RoomEffectTask 列表
   - 接收 lane snapshot
   - 接收 controller / stream / notifier

6. 你需要尽量让 stage 未来可以挂回 VoiceRoomPage 内部，但本线程先不要大改 voice_room_page.dart。

你的明确写入范围：

- 可以新增和修改：
  - lib/modules/room_effect/presentation/**

- 如有必要，可少量只读参考：
  - lib/ui_kit/widgets/room/anim/l_gift_animal_view.dart
  - lib/ui_kit/widgets/room/anim/room_entrance_screen.dart
  - lib/ui_kit/widgets/room/anim/room_gift_seat_flight_overlay.dart
  - lib/ui_kit/widgets/room/effect/vapp_svga_layer_widget.dart

你的禁止写入范围：

- 不要修改：
  - lib/services/audio/rtm_manager.dart
  - lib/services/audio/rtc_manager.dart
  - lib/modules/room/voice_room_page.dart
  - lib/main.dart
  - 线程 A 负责的新 engine/domain/application 文件

你的产出要求：

- 交付可读、清晰的 RoomEffectStage 与 layer 结构
- 接口命名必须对齐公共约定
- 在最终回复中列出：
  - 你新增的 layer 文件
  - 每个 layer 准备承接哪类任务
  - 还依赖线程 A 提供哪些 engine 能力
```

---

### 线程 C Prompt

用途：

- 负责旧链路入口收口与适配层

直接投喂：

```text
在遵守“公共约定 prompt”的前提下，执行线程 C 的任务。

你的职责是：把现有语言房中的特效触发入口统一改成“事件投递”，尽量不碰 presentation 层结构，不大改渲染细节。

你的主要目标：

1. 梳理并改造当前这些文件里的直接特效触发点：
   - lib/services/audio/rtm_manager.dart
   - lib/services/audio/rtc_manager.dart
   - lib/modules/room/voice_room_page.dart
   - lib/services/gift/gift_system_manager.dart

2. 找出以下直接触发方式并逐步收口：
   - 直接 SCGiftVapSvgaManager().play(...)
   - 直接 OverlayManager().addMessage(...)
   - 直接往独立动画队列入队
   - 页面层自己拼装多个动画副作用

3. 你的目标不是立刻删掉所有旧逻辑，而是先把“触发入口”统一改成投递 RoomEffectEvent 或等价事件。

4. 你需要新增或实现适配层，建议命名：
   - RoomEffectEventAdapter
   - 或等价 wiring 文件

5. 需要特别注意去重场景：
   - 本地自己进房 + 群消息回流
   - 本地自己送礼 + 房间消息回流
   - 幸运礼物广播 + 房间群消息双到达

6. 必须保留当前礼物业务判断口径，不要修改：
   - 哪些礼物触发全屏
   - 哪些礼物触发飘屏
   - customAnimationCount 的使用方式
   - 幸运礼物 burst 口径

你的明确写入范围：

- 可以修改：
  - lib/services/audio/rtm_manager.dart
  - lib/services/audio/rtc_manager.dart
  - lib/modules/room/voice_room_page.dart
  - lib/services/gift/gift_system_manager.dart

- 可以新增：
  - lib/modules/room_effect/application/room_effect_event_adapter.dart
  - 或你认为更合适但职责清晰的 adapter/binding 文件

你的禁止写入范围：

- 不要修改：
  - lib/main.dart
  - lib/modules/room_effect/presentation/**
  - 线程 B 新增的 stage/layer 文件
  - 线程 A 的核心 engine 接口定义

你的产出要求：

- 最终让旧入口尽量先统一走事件
- 即便 engine/stage 还未最终接上，也要把触发点收成统一入口
- 在最终回复中列出：
  - 你改掉了哪些直接触发点
  - 每类事件映射成了什么 RoomEffectEvent
  - 哪些旧逻辑你暂时保留未删
```

---

### 线程 D Prompt

用途：

- A/B/C 合并后再启动，负责收尾、清理、挂载调整与回归

直接投喂：

```text
在遵守“公共约定 prompt”的前提下，执行线程 D 的任务。

注意：这个线程默认在 A/B/C 已经完成并合并后再启动。你的职责是最终收尾，不是从零搭骨架。

你的主要目标：

1. 把房间专属特效层尽量从根层收回房间内部，重点检查：
   - lib/main.dart
   - lib/modules/room/voice_room_page.dart

2. 清理旧双轨逻辑，重点检查：
   - lib/ui_kit/widgets/room/anim/room_entrance_widget.dart
   - 旧的 RoomEntranceHelper 残留引用
   - 不再需要的直接 play/addMessage 入口

3. 统一房间生命周期清理：
   - 退房
   - 最小化
   - 切房
   - 房间页面销毁

4. 回归以下重点问题：
   - 房间退出后礼物图或飞向麦位残留
   - 房间飘屏跑到首页
   - 进场与全屏特效并发时队列紊乱
   - 幸运礼物逻辑回归

5. 你可以少量补充 metrics 或 debug log，但不要无限制新增临时调试代码。

你的明确写入范围：

- 可以修改：
  - lib/main.dart
  - lib/modules/room/voice_room_page.dart
  - lib/shared/data_sources/sources/local/floating_screen_manager.dart
  - lib/shared/tools/sc_room_effect_scheduler.dart
  - lib/ui_kit/widgets/room/anim/room_entrance_widget.dart
  - 其它你确认属于“旧链路清理 / 最终挂载调整 / 生命周期回收”的文件

你的禁止写入范围：

- 不要推翻线程 A 已经稳定的 engine 核心接口
- 不要重命名线程 B 已经落好的 presentation 核心对象
- 不要重新发明第二套 adapter 或第二套 lane

你的产出要求：

- 最终让新链路成为主链路
- 旧链路要么删除，要么明确降级成只读残留且不再实际生效
- 在最终回复中列出：
  - 你清理了哪些旧链路
  - 你改了哪些根层/房间层挂载
  - 你验证了哪些关键回归项
  - 你认为还剩哪些适合下一轮继续处理
```

---

### 推荐投喂顺序

建议你后面实际开线程时，按这个顺序喂：

1. 给 A、B、C 同时发送“公共约定 prompt”
2. 再分别发送各自的线程 prompt
3. 等 A、B、C 产出后完成合并
4. 最后再给 D 发送“公共约定 prompt + 线程 D prompt”

### 推荐合并检查点

在真正合并 A/B/C 前，建议你人工确认一次这几个点：

- A 的对象命名和 B/C 预期一致
- B 的 stage/layer 命名没有另起炉灶
- C 没有继续保留太多直接 `play()` 或 `addMessage()` 的新入口
- 三边没有同时改坏 `voice_room_page.dart / rtm_manager.dart / rtc_manager.dart`

---

## 最终建议

最终建议仍然是：

- **先重构语言房特效系统**
- **不先重构整套语言房**
- **先统一入口、统一引擎、统一生命周期**
- **尽量保留当前礼物业务逻辑与视觉**

这样做的收益最大，风险也最可控。

如果后续按本文实施，建议第一步从“阶段 0 + 阶段 1”开始，即：

- 先建事件模型和指标
- 再把所有直接触发动画的入口统一改成投递事件

一旦这一步完成，后面每条特效链路都可以逐条平滑迁移，不需要再一次性大改整间房。