youle_cocos/docs/superpowers/plans/2026-09-08-room-platform-refactor.md

房间平台重构实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. 本计划按依赖顺序执行，不隐含并行代理授权。

Goal: 在服务器与协议不变的前提下，实现平台无具体游戏依赖、明确房间生命周期和易用的子游戏接入边界。

Architecture: 模块化单体；保留现有网络、状态缓存、会话租约，逐步引入唯一游戏装配、RoomCoordinator/Scope、带来源的输入和公共能力端口。

Tech Stack: TypeScript、Cocos Creator 3.8.8、现有 Node 测试、Funplay Cocos MCP。

Status: 平台核心重构已实施，执行证据见 实施记录。未支持的音频所有权与真实账号/原生设备验收单独标记，不作为已通过项。

设计依据：架构设计、接口迁移。

0. 执行约束

• 使用主工作区 G:/Works/YouleGamesCocosCreator/cocoscreator_projects/YouleNexus，按用户约定在主 checkout 分支工作，不自动 stash 或创建 worktree。
• 每阶段开始记录已有修改；序列化资产必须经 Cocos MCP。不得为精简 diff 手改 prefab/scene/meta。
• 不修改 server；只读核对协议来源。不修改 projects/Game_Surface_3 的旧实现来迎合新测试。
• 新旧处理器不同时消费同一业务消息。每阶段都保持一个权威状态来源。
• 测试失败先确认原因，不能通过降低断言、吞异常、补默认值实现“通过”。
• 以下建议新文件名是实施目标；若现有模块已承担相同职责，优先提取/复用而非再建一份。
• 完成各任务后保留可独立审查的 diff；提交/合并按用户另行授权，不自动提交当前混合修改。

1. 任务依赖

P0 基线与契约夹具
  → P1 唯一游戏装配
  → P2 不透明载荷与游戏输入
  → P3 房间生命周期和顺序
  → P4 公共能力与游戏投影
  → P5 增量展示与资源
  → P6 双游戏接入和发布边界验证

P5 不与 P3/P4 同时改同一 UI 生命周期。完整玩法、回放和非当前支持的 VIP/百人场另行拆任务，不扩大本计划范围。

2. P0：冻结兼容基线与资源检查

涉及文件：

• framework-tests/platform/runtime.test.ts、runtime-session.test.ts。
• framework-tests/protocol/，新增房间入口/开战矩阵测试。
• framework-tests/fixtures/contracts/，增加经脱敏且标明来源的夹具。
• scripts/check-import-boundaries.mjs 及现有 architecture 测试。
• 新增资源装配检查脚本/测试，路径以现有 architecture 测试组织为准。

步骤：

• 记录 git 状态和任务可能涉及的 scene/prefab/meta 哈希，不覆盖未提交工作。
• 对照原 Desk/Net 为创建、登录、加入、开战、解散建立事件顺序断言。
• 用含两个 CreateRoomPage 的夹具验证资源检查会失败，避免重复本次模板脚本残留问题。
• 给现有资产执行只读装配检查，记录发现而非批量自动删除组件。
• 运行当前相关测试，区分已有失败与此次新增断言揭示的缺口。
• 记录目标设备、场景加载、消息密度与聊天长度的测量方法；绝对阈值未确认时不得填假数字。

完成条件：有清晰的已支持范围、真实业务路径基线和可复现的装配错误检查。尚未接入的开战路径标明缺口，不用空钩子变绿。

3. P1：唯一游戏装配

涉及文件：

• assets/scripts/platform-login/PlatformStartup.ts、SubgameAssets.ts、lobby-panel.ts。
• assets/games/erqiwang/、assets/games/template/ 的工厂和页面。
• 新增 assets/app/composition/ 和共享装配契约。
• framework/presentation/room-chat-config.ts 的具体游戏内容迁移到游戏定义。

步骤：

• 先写注册/装配测试：两款游戏分别得到自己的创建页、房间 View、规则和 route。
• 建立一个权威游戏定义；配置身份按引用注入，不复制渠道常量。
• 将 PlatformStartup 中具体游戏工厂/View 分支移入组合根。
• 将游戏聊天内容与声明的策略移出公共 framework，公共解析器接收注入内容。
• 更新边界检查，公共 scripts/ui 与 framework 一并检查，仅允许明确 app 根依赖两侧。
• 通过 MCP 更新需要变化的资源引用，保留资源 UUID，验证页面唯一性。
• 在编辑器从真实创建按钮验证：二七王提交 11 位字符串、模板仍提交自己的数组。

完成条件：增加游戏只改该游戏目录与组合注册，公共启动代码不含 gameKey 条件分支；保存后的资源重新加载仍正确。

4. P2：不透明载荷与完整游戏输入

涉及文件：

• framework/sdk/contracts/roomtype.ts、game-module.ts、platform-events.ts。
• framework/protocol/contracts/room-contracts.ts 与 validation。
• framework/protocol/platform-handlers.ts、first-slice-routes.ts。
• framework/platform/runtime-session.ts、platform/stores/。
• 游戏协议适配与相应 runtime/protocol 测试。

步骤：

• 编写传输保持测试：字符串、数组、对象、有限标量在允许的字段位置保持值和类型；undefined/循环/非有限数字拒绝。
• 搜索全部 roomtype 消费方，消除平台的 length/index/格式判断；游戏校验保持在游戏入口。
• 定义带来源的 create/login/join/started/settlement 输入；不删除未知载荷字段。
• 对照原协议补齐 self_makewar/makewar 和附带 deskwar 的 player_prepare/other_join_room。
• 验证准备提交在 started 之前，StartWar 等效入口拿到整包，Reconnect/DeskInfo 拿到各自快照。
• 逐个切换游戏适配器，不让旧 restore 与新输入重复执行。
• 测试非法游戏配置仍由游戏拒绝，而不是平台补值。

完成条件：入口语义无合并丢失，公共协议与玩法协议边界清晰；实际发包内容不因内部类型升级而变化。

5. P3：房间协调器与异步生命周期

涉及文件：

• 提取 framework/platform/room/{room-coordinator,room-scope,room-mailbox,room-entry}.ts。
• runtime.ts 的 SceneOrderedGameSessionHost、runtime-session.ts。
• PlatformStartup.ts 的 showRoom/房间释放部分和场景适配。
• game-host-adapter.ts 的租约和数字工具延期逻辑。

步骤：

• 用可控 Promise 写失败测试：mount 未完成时不得调用依赖就绪的进入逻辑。
• 增加 generation 与 scope，复用现有租约失效机制，避免两套互相独立的有效性判断。
• 实现预检、进入、就绪、失败清理；失败后不得暴露 active 半状态。
• 为加载期间消息建立有界 FIFO；配置中显式提供容量/超时。
• 验证踢出/断线/取消能越过慢加载终止 scope，旧回调晚到只清理自身资源。
• 覆盖普通换服与解散换服，不误销毁需要继续结算的上下文。
• 将重复页面延迟逻辑收敛到统一就绪/取消契约，保留必要的能力冲突规则。
• 验证清理抛错时其他清理仍执行，正常离开和进入失败使用同一 scope 释放路径。

完成条件：创建/加入/恢复在慢加载、连续切房和控制消息插入情况下顺序可预测；业务消息不等待动画，陈旧回调不能发包/写状态。

6. P4：能力端口与游戏事实投影

涉及文件：

• sdk/contracts/game-host.ts，提取能力契约文件。
• platform/game-host-adapter.ts、房间公共命令与策略。
• presentation/deferred-numeric-tools.ts、数字输入/倍率模型。
• RoomPlatformPanels.ts、RoomHud.ts、NumericToolsPanel.ts。
• 游戏模型的只读 GameRoomProjection 与展示选择器。

步骤：

• 写接口边界测试：游戏不能直接修改公共玩家、资产、准备状态。
• 区分平台 room stage、游戏 round phase、自身参与状态和局内分数。
• 实现只读投影订阅与组合选择器，测试同一消息只产生完整的展示版本。
• 定义 room/messages/ui/audio/scope 分组能力，移除公共类型对具体 adapter 的反向引用。
• 数字/倍率请求返回 confirmed/cancelled，离房和替换有确定结果；重叠策略测试先行。
• loading/tips 已接入所有者句柄并通过冲突清理测试；audio 因原生没有停止契约，未发布所有者端口。
• 平台 start/prepare/exit 等命令统一填身份，按钮和摇一摇复用命令策略。
• 保留浏览器适配器来源定义的默认行为，不在 UI 再造 fallback。

完成条件：无任意 patchRoom；游戏可以表达玩法公共展示需要的事实；输入与能力资源不会跨房间泄漏。

7. P5：聊天与资源增量优化

涉及文件：

• RoomChatPanel.ts、RoomUi.ts、聊天状态模型。
• 新增头像资源租约适配与必要的缓存策略。
• ApplyVotePanel.ts、RoomNoticePanel.ts、HUD 倒计时相关代码仅在明确优化点修改。

步骤：

• 建立追加聊天的基线：新消息前后节点身份、纹理创建数、布局次数和滚动位置。
• 为消息增加本地稳定 ID，按 ID 追加/更新/移除，网络包不增加字段。
• 头像请求去重与租约释放；验证 URL 变化时旧加载不覆盖新行。
• 增加“用户已上翻历史则保持位置”的交互测试。
• 合并同帧绘制并跳过无关选择器更新，业务事件顺序保持不变。
• 后台恢复时倒计时重新计算，定时器不作为结算判断依据。
• 根据基线决定是否需要可变行高虚拟列表；数据规模不足时不引入。

完成条件：追加一条聊天不销毁已有历史行；同 URL 不重复建纹理；真实 Cocos 交互通过；性能报告列出设备与测试场景，不只报告 Node 测试耗时。

8. P6：接入套件与整体验收

步骤：

• 模板与二七王使用相同公共 SDK，验证不同 roomtype 类型端到端保持。
• 运行创建/加入/登录恢复/开战/投票/结算/退出矩阵，记录未实现玩法。
• 加载中退出、踢出、换服、重复回包、队列超限、清理失败均有负例。
• 100 次房间进入/退出后检查节点、订阅、计时器和资源租约回到基线。
• 检查编译产物中的资源与调用路径，避免源码正确而预览仍使用旧资产。
• 对每个迁移过的原接口更新本迁移清单的落地位置和状态。
• Cocos/Windows 本地预览和协议夹具验证已执行；真实服务器账号整局联调、Android/iOS 原生设备验收未执行。Web 构建证据见实施记录。

完成条件：新增第二款游戏无需改平台核心；源码与资源边界均通过；明确列出游戏玩法和模式尚未支持项。

9. 验证命令

以下从 G:/Works/YouleGamesCocosCreator/cocoscreator_projects 执行。具体测试集随任务扩大，未改变的测试不反复运行；先跑相关集，再在集成阶段跑完整要求。

node --experimental-transform-types --test framework-tests/platform/runtime.test.ts framework-tests/platform/runtime-session.test.ts
node --experimental-transform-types --test framework-tests/net/wire-client.test.ts framework-tests/presentation/erqiwang-room-entry.test.ts
node node_modules/typescript/bin/tsc -p tsconfig.framework.json --noEmit
node node_modules/typescript/bin/tsc -p YouleNexus/tsconfig.json --noEmit --ignoreDeprecations 6.0 --skipLibCheck --lib ES2020,DOM --types node --strict
node scripts/check-import-boundaries.mjs

新增测试路径在创建后加入命令；不把未创建的测试列为已经执行。Cocos prefab/scene 校验与真实交互走 MCP，结构引用通过不等于视觉/交互通过。

10. 回退与交付

每个阶段限定文件和资产清单，留存阶段前后验证结果。回退以该阶段精确 diff 为单位，不批量 restore 用户工作区，也不删除整个 library 缓存。

若生命周期改动暴露业务缺口，停止扩大范围，补齐该路径契约和测试；不能恢复为宽松默认值。阶段交付报告写清：改变了什么、兼容路径、测试证据、未实现能力、下一阶段依赖。

本计划不附带部署、提交或合并动作；这些与完成本地阶段实现分别管理。