joywayer
35216f75e7
Complete room UI and protocol integration, move game definitions and resources behind bundle entries, publish authoritative version XML, and document single-game builds. Include all current resource changes and experiment artifacts.
203 lines
12 KiB
Markdown
203 lines
12 KiB
Markdown
# 房间平台重构实施计划
|
|
|
|
> **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:** 平台核心重构已实施，执行证据见 [实施记录](../implementations/2026-09-08-room-platform-refactor.md)。未支持的音频所有权与真实账号/原生设备验收单独标记，不作为已通过项。
|
|
|
|
设计依据：[架构设计](../specs/2026-09-08-room-platform-architecture.md)、[接口迁移](../specs/2026-09-08-room-platform-api-migration.md)。
|
|
|
|
## 0. 执行约束
|
|
|
|
- 使用主工作区 `G:/Works/YouleGamesCocosCreator/cocoscreator_projects/YouleNexus`，按用户约定在主 checkout 分支工作，不自动 stash 或创建 worktree。
|
|
- 每阶段开始记录已有修改；序列化资产必须经 Cocos MCP。不得为精简 diff 手改 prefab/scene/meta。
|
|
- 不修改 server；只读核对协议来源。不修改 `projects/Game_Surface_3` 的旧实现来迎合新测试。
|
|
- 新旧处理器不同时消费同一业务消息。每阶段都保持一个权威状态来源。
|
|
- 测试失败先确认原因，不能通过降低断言、吞异常、补默认值实现“通过”。
|
|
- 以下建议新文件名是实施目标；若现有模块已承担相同职责，优先提取/复用而非再建一份。
|
|
- 完成各任务后保留可独立审查的 diff；提交/合并按用户另行授权，不自动提交当前混合修改。
|
|
|
|
## 1. 任务依赖
|
|
|
|
```text
|
|
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 测试组织为准。
|
|
|
|
步骤：
|
|
|
|
- [x] 记录 git 状态和任务可能涉及的 scene/prefab/meta 哈希，不覆盖未提交工作。
|
|
- [x] 对照原 Desk/Net 为创建、登录、加入、开战、解散建立事件顺序断言。
|
|
- [x] 用含两个 CreateRoomPage 的夹具验证资源检查会失败，避免重复本次模板脚本残留问题。
|
|
- [x] 给现有资产执行只读装配检查，记录发现而非批量自动删除组件。
|
|
- [x] 运行当前相关测试，区分已有失败与此次新增断言揭示的缺口。
|
|
- [x] 记录目标设备、场景加载、消息密度与聊天长度的测量方法；绝对阈值未确认时不得填假数字。
|
|
|
|
完成条件：有清晰的已支持范围、真实业务路径基线和可复现的装配错误检查。尚未接入的开战路径标明缺口，不用空钩子变绿。
|
|
|
|
## 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` 的具体游戏内容迁移到游戏定义。
|
|
|
|
步骤：
|
|
|
|
- [x] 先写注册/装配测试：两款游戏分别得到自己的创建页、房间 View、规则和 route。
|
|
- [x] 建立一个权威游戏定义；配置身份按引用注入，不复制渠道常量。
|
|
- [x] 将 PlatformStartup 中具体游戏工厂/View 分支移入组合根。
|
|
- [x] 将游戏聊天内容与声明的策略移出公共 framework，公共解析器接收注入内容。
|
|
- [x] 更新边界检查，公共 scripts/ui 与 framework 一并检查，仅允许明确 app 根依赖两侧。
|
|
- [x] 通过 MCP 更新需要变化的资源引用，保留资源 UUID，验证页面唯一性。
|
|
- [x] 在编辑器从真实创建按钮验证：二七王提交 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 测试。
|
|
|
|
步骤：
|
|
|
|
- [x] 编写传输保持测试：字符串、数组、对象、有限标量在允许的字段位置保持值和类型；undefined/循环/非有限数字拒绝。
|
|
- [x] 搜索全部 roomtype 消费方，消除平台的 length/index/格式判断；游戏校验保持在游戏入口。
|
|
- [x] 定义带来源的 create/login/join/started/settlement 输入；不删除未知载荷字段。
|
|
- [x] 对照原协议补齐 self_makewar/makewar 和附带 deskwar 的 player_prepare/other_join_room。
|
|
- [x] 验证准备提交在 started 之前，StartWar 等效入口拿到整包，Reconnect/DeskInfo 拿到各自快照。
|
|
- [x] 逐个切换游戏适配器，不让旧 restore 与新输入重复执行。
|
|
- [x] 测试非法游戏配置仍由游戏拒绝，而不是平台补值。
|
|
|
|
完成条件：入口语义无合并丢失，公共协议与玩法协议边界清晰；实际发包内容不因内部类型升级而变化。
|
|
|
|
## 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` 的租约和数字工具延期逻辑。
|
|
|
|
步骤：
|
|
|
|
- [x] 用可控 Promise 写失败测试：mount 未完成时不得调用依赖就绪的进入逻辑。
|
|
- [x] 增加 generation 与 scope，复用现有租约失效机制，避免两套互相独立的有效性判断。
|
|
- [x] 实现预检、进入、就绪、失败清理；失败后不得暴露 active 半状态。
|
|
- [x] 为加载期间消息建立有界 FIFO；配置中显式提供容量/超时。
|
|
- [x] 验证踢出/断线/取消能越过慢加载终止 scope，旧回调晚到只清理自身资源。
|
|
- [x] 覆盖普通换服与解散换服，不误销毁需要继续结算的上下文。
|
|
- [x] 将重复页面延迟逻辑收敛到统一就绪/取消契约，保留必要的能力冲突规则。
|
|
- [x] 验证清理抛错时其他清理仍执行，正常离开和进入失败使用同一 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 与展示选择器。
|
|
|
|
步骤：
|
|
|
|
- [x] 写接口边界测试：游戏不能直接修改公共玩家、资产、准备状态。
|
|
- [x] 区分平台 room stage、游戏 round phase、自身参与状态和局内分数。
|
|
- [x] 实现只读投影订阅与组合选择器，测试同一消息只产生完整的展示版本。
|
|
- [x] 定义 room/messages/ui/audio/scope 分组能力，移除公共类型对具体 adapter 的反向引用。
|
|
- [x] 数字/倍率请求返回 confirmed/cancelled，离房和替换有确定结果；重叠策略测试先行。
|
|
- [ ] loading/tips 已接入所有者句柄并通过冲突清理测试；audio 因原生没有停止契约，未发布所有者端口。
|
|
- [x] 平台 start/prepare/exit 等命令统一填身份，按钮和摇一摇复用命令策略。
|
|
- [x] 保留浏览器适配器来源定义的默认行为，不在 UI 再造 fallback。
|
|
|
|
完成条件：无任意 patchRoom；游戏可以表达玩法公共展示需要的事实；输入与能力资源不会跨房间泄漏。
|
|
|
|
## 7. P5：聊天与资源增量优化
|
|
|
|
涉及文件：
|
|
|
|
- `RoomChatPanel.ts`、`RoomUi.ts`、聊天状态模型。
|
|
- 新增头像资源租约适配与必要的缓存策略。
|
|
- `ApplyVotePanel.ts`、`RoomNoticePanel.ts`、HUD 倒计时相关代码仅在明确优化点修改。
|
|
|
|
步骤：
|
|
|
|
- [x] 建立追加聊天的基线：新消息前后节点身份、纹理创建数、布局次数和滚动位置。
|
|
- [x] 为消息增加本地稳定 ID，按 ID 追加/更新/移除，网络包不增加字段。
|
|
- [x] 头像请求去重与租约释放；验证 URL 变化时旧加载不覆盖新行。
|
|
- [x] 增加“用户已上翻历史则保持位置”的交互测试。
|
|
- [x] 合并同帧绘制并跳过无关选择器更新，业务事件顺序保持不变。
|
|
- [x] 后台恢复时倒计时重新计算，定时器不作为结算判断依据。
|
|
- [x] 根据基线决定是否需要可变行高虚拟列表；数据规模不足时不引入。
|
|
|
|
完成条件：追加一条聊天不销毁已有历史行；同 URL 不重复建纹理；真实 Cocos 交互通过；性能报告列出设备与测试场景，不只报告 Node 测试耗时。
|
|
|
|
## 8. P6：接入套件与整体验收
|
|
|
|
步骤：
|
|
|
|
- [x] 模板与二七王使用相同公共 SDK，验证不同 roomtype 类型端到端保持。
|
|
- [x] 运行创建/加入/登录恢复/开战/投票/结算/退出矩阵，记录未实现玩法。
|
|
- [x] 加载中退出、踢出、换服、重复回包、队列超限、清理失败均有负例。
|
|
- [x] 100 次房间进入/退出后检查节点、订阅、计时器和资源租约回到基线。
|
|
- [x] 检查编译产物中的资源与调用路径，避免源码正确而预览仍使用旧资产。
|
|
- [x] 对每个迁移过的原接口更新本迁移清单的落地位置和状态。
|
|
- [ ] Cocos/Windows 本地预览和协议夹具验证已执行；真实服务器账号整局联调、Android/iOS 原生设备验收未执行。Web 构建证据见实施记录。
|
|
|
|
完成条件：新增第二款游戏无需改平台核心；源码与资源边界均通过；明确列出游戏玩法和模式尚未支持项。
|
|
|
|
## 9. 验证命令
|
|
|
|
以下从 `G:/Works/YouleGamesCocosCreator/cocoscreator_projects` 执行。具体测试集随任务扩大，未改变的测试不反复运行；先跑相关集，再在集成阶段跑完整要求。
|
|
|
|
```powershell
|
|
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 缓存。
|
|
|
|
若生命周期改动暴露业务缺口，停止扩大范围，补齐该路径契约和测试；不能恢复为宽松默认值。阶段交付报告写清：改变了什么、兼容路径、测试证据、未实现能力、下一阶段依赖。
|
|
|
|
本计划不附带部署、提交或合并动作；这些与完成本地阶段实现分别管理。
|