hy/chatapp3-flutter

Fork 0

roxy 5086cdd97c bug fix

2026-04-22 20:08:45 +08:00

45 KiB

Raw Blame History

语言房重构方案

文档目的

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

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

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

本方案的核心原则是：

尽可能保留当前礼物业务逻辑、素材、阈值和视觉表现
先重构特效系统，不一次性推倒 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 仍保留

根因判断

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

多源头直接驱动 UI
RTM/RTC/RoomPage/GiftSystem 都可能直接触发动画。
多条高频动画链路并发
全屏 VAP/SVGA、顶部礼物条、进场 banner、飞向麦位、房间飘屏可能同时争抢主线程。
房间特效不是一个完整子系统
现在只有局部管理器，没有一个真正拥有“总入口、总队列、总预算、总生命周期”的 runtime。
业务状态更新和特效播放距离太近
房间麦位刷新、在线用户刷新、消息列表更新，会和特效播放共享同一个页面状态环境。
生命周期边界偏松
房间退出后，根层 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 表达方式	保留视觉，不一定保留旧实现

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

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

目标架构

架构总览

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 调度
真正的渲染层只负责展示，不再关心业务来源

模块	职责	说明
`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

为什么要有标准化事件层

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

目标任务模型

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

一个 task 建议至少包含：

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

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

页面挂载方式调整

当前问题

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

全屏 VapPlusSvgaPlayer
RoomGiftSeatFlightOverlay

这意味着：

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

目标方式

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

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，一边让多个线程各自发明自己的事件模型
不建议一开始就多个线程同时删旧链路

并行原则

先统一接口，再并行开发
至少先约定好以下对象名和职责：
- RoomEffectEvent
- RoomEffectTask
- RoomEffectLane
- RoomEffectEngine
- RoomEffectStage
- RoomEffectEventAdapter
新文件优先并行，旧文件尽量收口到单一线程
新增模块最适合多线程拆分；旧有入口文件应尽量减少多人同时修改。
先搭骨架，再接现有链路
先让 engine 与 stage 的框架稳定，再开始把 RTM/RTC/VoiceRoomPage 接上去。
收尾一定要串行
旧链路删除、层级调整、房间生命周期回收、回归修 bug，这些必须收口到最后一个线程统一处理。

最稳的执行顺序

推荐按下面顺序跑，而不是 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

推荐合并顺序：

先合线程 A
先把 engine 和模型定住，避免后续接口继续漂。
再合线程 B
让 stage 和 layer 按 A 的接口接上。
再合线程 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 核心接口

不同并行强度的建议

最稳方案

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 线程时直接复制使用的。

推荐使用方式：

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

公共约定 Prompt

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

你现在在 /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 基础层

直接投喂：

在遵守“公共约定 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 承载层

直接投喂：

在遵守“公共约定 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

用途：

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

直接投喂：

在遵守“公共约定 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 合并后再启动，负责收尾、清理、挂载调整与回归

直接投喂：

在遵守“公共约定 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

你的产出要求：

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

最终建议

最终建议仍然是：

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

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

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

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

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

45 KiB Raw Blame History Unescape Escape

语言房重构方案

文档目的

当前建议结论

当前架构现状

当前核心模块

当前核心问题

根因判断

重构目标

目标

非目标

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

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

目标架构

架构总览

核心思想

推荐模块拆分图

各模块职责

目标事件模型

推荐事件类型

为什么要有标准化事件层

目标任务模型

推荐的 lane 划分

页面挂载方式调整

当前问题

目标方式

结果

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

可复用项

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

调度与降级策略

首轮策略

建议规则

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

迁移顺序

阶段 0：建立基线与指标

阶段 1：统一事件入口

阶段 2：落地 RoomEffectEngine

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

阶段 4：迁移 fullscreen lane

阶段 5：迁移 entrance lane

阶段 6：迁移 giftTicker lane

阶段 7：迁移 seatFlight lane

阶段 8：迁移 floating lane

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

关键兼容策略

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

2. 消息协议不动

3. 参数冻结后再迁移

风险点列表

回归测试清单

礼物链路

进场链路

飘屏链路

生命周期

性能

验收指标建议

目标方向

预计实施节奏

多线程并行执行方案

并行收益预估

并行原则

推荐线程划分

线程 A：Engine 基础层

线程 B：Stage 与渲染承载层

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

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

最稳的执行顺序

第 1 步：接口冻结

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

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

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

推荐的文件写入边界

推荐的并行里程碑

里程碑 1

里程碑 2

里程碑 3

里程碑 4

不同并行强度的建议

最稳方案

45 KiB

Raw Blame History

阶段 2：落地 `RoomEffectEngine`

阶段 4：迁移 `fullscreen lane`

阶段 5：迁移 `entrance lane`

阶段 6：迁移 `giftTicker lane`

阶段 7：迁移 `seatFlight lane`

阶段 8：迁移 `floating lane`