AdLike2048/docs/方案-资源与UI生命周期.md

方案：资源与 UI 生命周期

日期：2026-09-14
原则：状态机完整、所有权成对、失败报错；预载只是提示，不参与打开决策。

1. 面板状态

每个 uiId 只能处于：空闲 → 打开中 → 已打开 → 关闭中。

操作	规则
打开中再 openPanel	记下最新 OpenParam，等本次结束；成功则套用最新参数，失败则用最新参数重开
已打开再 openPanel	套用参数并 onInit，不二次 instantiate
打开中 close / abort	世代 +1，销毁已上屏节点，释放预制引用与 bundle owner，结束等待
关闭中再打开	先等关闭结束

每一处 await 之后必须核对打开世代；过期协程不得回写 _ui_map、不得再 pause。

2. 资源所有权

• 预制：bundle.get 命中由本面板 addRef；bundle.load 由引擎 +1，本面板持有该次引用。关闭 / 失败清理只 decRef 自己拿过的那一次。
• Bundle：openPanel 的 owner 为 ui:${panelId}。关闭或失败 releaseBundleOwner。永久包不登记。
• pauseBattle：UIManager 内 _pauseHeld 与 acquire/release 成对；入队、开始打开即持有，出队未开、打开失败、关闭、abort 即释放。

3. 弹窗队列

一次只展示一个。推进时机：popPanel、当前窗关闭、当前窗打开失败。禁止 0.5s 轮询双开。

4. 下载

运行时 loadBundle 只经 BundleLifecycle.ensureLoaded（同名合并）。SpriteLoad / openPanel 不得再打原生 loadBundle。

预制 bundle.load 只经 ResourcesManager.loadRes（同路径合并）。openPanel 与静默预载不得再打原生 bundle.load / bundle.preload，否则小游戏上第二回调可能永不回来，体感「loading 后打开失败，之后再也打不开」。

静默预载：

• popCommon zip 在 Boot 三分包落地后 kickLoad，进战不卸。
• HallWarmRes（设置/体力/Toast）：回大厅优先 decode；进战 invalidate 释放预制，打开再 load。
• 其它大厅页：HallWarm 完成后再 silent；与 openPanel 共用 ResourcesManager.loadRes。
• 打开不 await 预载。

失效的 bundle.get 必须剔除后重载，禁止当作失败直接 return。

5. 排行榜头像

• 纯数字 = Headicon.id：表无行则报错并隐藏，不得当 URL。
• 非数字 = 远程图：SpriteLoad 记住 URL，disable/enable 后按 URL 重拉。
• 空字段 = 无头像，隐藏。

icons 未落地时由 ensureLoaded 等待同一次原生下载，失败 console.error。