joywayerandClaude Opus 5
02dc5d51ca
主要改动: - 切到 funplay-cocos-mcp v0.5.1 (用户级配置, 项目级 .mcp.json 删除) - 仓库文档/CLAUDE.md/.gitignore 等清理过时 cocos-mcp-server 引用 - memory 文件同步: cocos-mcp-setup/path/blocker/spriteframe-uuid/prefab-persist 等加 funplay 实测警告 - memory 新建 funplay-cocos-mcp-pending-verification.md (后已被实测覆盖) - spec/plan/data: - docs/superpowers/specs/2026-09-02-legacy-layer-migration-design.md - docs/superpowers/plans/2026-09-02-legacy-layer-migration.md - docs/superpowers/data/layer-spirit-summary.json - YouleNexus: profiles.ts / defaults.ts / PlayerInfoView.prefab / scene 改动 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
143 lines
11 KiB
Markdown
143 lines
11 KiB
Markdown
# 平台逻辑移植（子系统 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 落地后返工。
|