youle_cocos/docs/superpowers/plans/2026-08-30-platform-logic-migration.md

平台逻辑移植（子系统 C）开发计划 —— 从当前进度到「逻辑流程一致」验收

For agentic workers: 执行时使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans，任务用 - [ ] checkbox 跟踪。 顶层路线图：本计划定义阶段边界、依赖、验收；阶段 1 直接续用 2026-06-28-platform-store.md，阶段 4/5 复用 2026-08-27-ui-asset-and-skin.md、2026-08-28-legacy-ui-migration.md，阶段 2/3 为新增（执行时各自展开为 TDD 任务）。

Goal: 把子系统 C 规范（docs/superpowers/specs/2026-08-30-legacy-platform-logic-migration.md）的 §3 落点全部落地，使 §8 的 10 条「逻辑流程一致性检查点」全部通过。

策略假设（可纠正点）：端到端逻辑主线优先，UI 大面积落地收尾——先打通「启动 → 建连 → 登录 → 进房/大厅 → 对局分发」这条纯逻辑主线（Store/session/protocol/sdk），UI 用最小占位（已有 Login_Layer.prefab）；最后再批量落地 55 界面。理由：C 规范的目标是「逻辑流程一致」而非「像素一致」，逻辑主线是协议契约与业务正确性的承重墙，UI 是响应式 Store 的下游视图、可后置。

基线（已完成，勿重复）：core（含 reactive.ts）、net（transport/net-client/envelope-codec/heartbeat/reconnect）、protocol（login + 4 rpc）、config（完整）、platform（player-store + types + readonly）、ui/theme。真机联调 player_login 往返已通过。

---

阶段总览（依赖图）

阶段1 三态机+session ──┐
                      ├─► 阶段2 协议+收包路由 ──► 阶段3 sdk+重连 ──► 阶段5 真机联调
阶段4 UI落地(并行) ────┘          (可与4并行)       (依赖2)
阶段5 原生桥(并行) ───────────────────────────────────────────────┘

阶段	内容	依赖	产出	复用现有 plan
1	platform 三态机 + session	无（reactive/types/player 已就绪）	AppStore/RoomStore/PlatformSession	✅ 2026-06-28-platform-store.md Task 4/5/6
2	启动接线 + protocol 补全 + 收包路由 + 房间事件	阶段 1	rpc 常量、Router、房间 handler、PlayerStore 补全	新写
3	sdk（IGameModule/GameContext）+ 断线重连	阶段 2	GameContext、IGameModule、deskinfo 透传	新写（= 原「Plan 5」主体）
4	UI 界面落地（55 界面 + FrameSet）	阶段 1（响应式 Store）	FrameSet 组件、界面控制器、批量 prefab	✅ 2026-08-28-legacy-ui-migration.md + 新写控制器
5	原生桥（WVJB）+ 真机端到端联调	阶段 3/4	完整 WVJB 桥、端到端验收	新写（= 原「Plan 5」收尾）

---

阶段 1：platform 三态机 + session（续现有 plan）

目标：AppStore(=GameData) / RoomStore(=Desk) / PlatformSession(=12_Logic 登录接入)，使 login 事件 → 三 Store 正确填充 + 相位流转。

直接续用 docs/superpowers/plans/2026-06-28-platform-store.md 的 Task 4（AppStore）、Task 5（RoomStore）、Task 6（PlatformSession）——该 plan 已含完整代码与测试，此处不重写，按原 TDD 流程执行。

• Task 4：platform/stores/app-store.ts（AppStore：setIdentity/setServers/setPhase/applyLogin）
• Task 5：platform/stores/room-store.ts（RoomStore：applyRecovery/clear，players 座位数组 + deskinfo opaque 透传）
• Task 6：platform/session.ts（PlatformSession 订阅 NetClient 事件总线 → 填充三 Store，相位流转）

验收：npm run test:framework 全绿（含 app-store 3 + room-store 3 + session 4 用例）；typecheck:framework exit 0；login 含 roomcode 时 RoomStore.inRoom=true + deskinfo 原样透传。

---

阶段 2：启动接线 + protocol 补全 + 收包路由 + 房间事件

目标：把「收包 → 路由分界 → Store 更新」这条主线打通，覆盖 C 规范 §4.1（路由分界）与 §6.2（登录分支）。

Task 2.1 — protocol 补全 rpc 常量（对应 C §3 02_Const 落点）

• 从旧 02_Const.js 的 RpcList（:13–109，~100 个）提取平台层 rpc，落 protocol/routes.ts（扩展 Rpc，保持函数名==rpc 字符串的同构映射）。
• 至少覆盖房间类 rpc（create_room/self_join_room/self_exit_room/other_exit_room/self_makewar/player_prepare/self_apply_free_room/change_seat/update_bean/connect_roomserver…）与玩家类（update_bean/set_sign/set_tel…）。
• 验收：Rpc 常量与 docs/protocol/ 的 rpc 字符串逐字节一致；typecheck 通过。

Task 2.2 — 收包路由分界（C §4.1 的红线）

• 在 net-client.ts（或新建 protocol/router.ts）实现 Router：route ∈ {platform,agent,room} → 平台 handler；route = <game route> → sdk 钩子（阶段 3 接上，本阶段先留 onGameRoute 空钩子 + 未注册时显式报错，不静默吞包）。
• connect_roomserver/connect_agentserver 换服逻辑已存在（net-client.ts:129-133），补「换服后重发登录」的触发。
• 验收：单测：platform 包 → 平台 handler 被调；对局 route 未注册 → 显式报错（第二准则：不兜底）。

Task 2.3 — 房间事件 handler → RoomStore/PlayerStore 更新（C §6.4）

• 新建 protocol/room.ts（或 platform/room-handlers.ts）：self_join_room/other_join_room/self_exit_room/other_exit_room/self_makewar/player_prepare/self/other_apply/agree/refuse_free_room/other_offline/online/change_seat → 更新 RoomStore（座位、stage、state、AgreeList）。
• PlayerStore 补全 update_bean/update_roomcard/setCharm/setSign/setTel（对应 C §3.1 消除双镜像：bean/roomcard 只写 PlayerStore，RoomStore.players[seat] 是同一响应式来源的投影）。
• 验收：单测：每个房间 rpc 收包 → RoomStore/PlayerStore 字段正确变化；解散投票 AgreeList 累积正确。

Task 2.4 — 启动接线（C §6.1 启动流程）

• 把 config/bootstrap 的 resolveBootstrap 结果接 AppStore.setIdentity/setServers；new PlatformSession(net.bus) + net.start()。
• 首屏门控四条件（资源/WS onopen/配置/加载计时器）合成一个「就绪信号」→ 登录页（UI 阶段 4 接，本阶段先暴露 AppStore.phase 状态）。
• 验收：启动编排单测：bootstrap → AppStore 身份/服务器就绪 → net.start 建连。

---

阶段 3：sdk（IGameModule/GameContext）+ 断线重连

目标：建立子游戏对接边界，收包路由对局分支接上 sdk，deskinfo 透传 + 断线重连恢复（C §4.1/§5 边界判据、§6.3）。

Task 3.1 — sdk/GameContext facade（C §3 08_Utl_Output 落点）

• 只读暴露：room/player（只读 Store）、net.send(route,rpc,data)、seat.toView(mySeat,target)（替代旧 ChangeToStatus）、ui 占位（toast/dialog）。
• 旧 08_Utl_Output.js 的只读 getter（getMyInfo/getRoomcode/getPlayerList/getMySeat…）→ facade 方法或直接只读 Store。
• 验收：单测：facade 只读、不可逆改 Store；seat.toView 与旧 ChangeToStatus 同结果。

Task 3.2 — IGameModule 接口 + 注册（框架 spec §4）

• 定义 IGameModule（route/onEnter/onExit/onReceive/onReconnect/serialize/平台钩子默认空实现）。
• 注册机制：子游戏注册自己，Router 据 route 分发对局包 → activeGame.onReceive。
• 验收：单测：注册 mock 子游戏 → 对局 route 包 → onReceive 被调；未注册 → 显式报错。

Task 3.3 — deskinfo 透传 + 断线重连（C §6.3）

• login 回包含 deskinfo（isbattle==1）→ RoomStore 只透传不解析 → activeGame.onReconnect(deskinfo)。
• 断线重连完整链路：net/reconnect 重连 → 重发登录 → deskinfo 恢复对局。
• 验收：集成测试：login(deskinfo) → onReconnect 收到原样快照；断线 → 重连 → 重发登录。

---

阶段 4（并行）：UI 界面落地

目标：从 55 界面中间描述批量落地 Cocos 界面，响应式订阅 Store，界面切换走 node.active + AppStore.currentScene（C §6.5）。

• Task 4.1 FrameSet 组件（B §3.4）：多帧图切帧的运行时载体（setFrame(n)，1 基帧号）。
• Task 4.2 界面控制器：登录/大厅/房间 + 各弹窗，subscribe 三 Store 自动刷新；Login_Layer.prefab 接入真实登录数据。
• Task 4.3 批量落地：复用 2026-08-28-legacy-ui-migration.md 的 convert 管线，把 55 个 layer JSON → prefab（当前仅 Login_Layer 已落）。
• Task 4.4 界面切换：AppStore.currentScene 状态替代 get_self(149,37) 哨兵。

验收：登录→大厅→房间 界面切换正确；帧动画走 FrameSet；UI 由 Store 响应式驱动（无手工刷新）。

---

阶段 5（并行收尾）：原生桥 + 真机端到端联调

• Task 5.1 WVJB 完整异步桥（原「Plan 5」）：window.settings 同步取值 + setupWebViewJavascriptBridge 异步注册，接口名/数据格式/URL 构造与旧逐字一致（native-bridge-contract 技能）。
• Task 5.2 真机端到端：登录 → 大厅 → 进房 → 对局（mock/seed 子游戏）→ 结算，联调本地服。
• Task 5.3 断线重连真机验证：isbattle==1 时 deskinfo 恢复对局。

---

验收标准（映射 C 规范 §8 检查点）

• 信封 {app,route,rpc,data} 逐字节对齐（✅ 已有，回归不破坏）
• 收包分界：platform/agent/room → 平台 handler；对局 route → onReceive；未注册显式报错（阶段 2/3）
• 发包 HTTP 兜底（netType==1）+ player_login 的 putMsg="playerLogin"（阶段 2）
• 启动门控四条件合成就绪信号（阶段 2）
• 登录分支：roomcode/deskinfo 有无 → 大厅 or 房间 or onReconnect（阶段 1/3）
• 断线重连 + deskinfo 恢复（阶段 3/5）
• 三态机单一来源，无双镜像（阶段 1/2）
• 对局态 deskinfo 平台层不解析、原样透传（阶段 3）
• 界面切换 node.active + currentScene，不搬 set_level（阶段 4）
• 原生接口逐字一致（阶段 5）

---

风险与依赖

1. UI 落地量大（55 界面、旧 9862 行）——通过「逻辑主线先行 + 响应式 Store 后置 UI」隔离，UI 延迟不阻塞阶段 2/3 的协议正确性验证。
2. 对局 route 的 sdk 分界是红线——阶段 2.2 先留「未注册显式报错」，避免静默吞包（第二准则）。
3. set_windows/players 完整建模等次要项——按 C §9.3 待验证清单在对应阶段落地时回填，不阻塞主线。
4. 换肤/打包（ui-asset-skin plan）——独立于本计划，需在阶段 4 UI 落地时同步执行（散图 → Auto Atlas 打包），避免 UI 落地后返工。