# Cocos Creator 平台框架与子游戏架构设计

- **日期**：2026-06-28
- **状态**：设计已确认，待转实施计划（writing-plans）
- **范围**：友乐棋牌平台在 Cocos Creator 下的新一代「平台框架 + 子游戏」架构
- **宿主工程**：`cocoscreator_projects/YouleNexus`（Cocos Creator 3.8.8）

---

## 0. 第一准则：服务器零改动

任何前端开发都必须完全遵循前后端数据包的协议与数据结构，做到**服务器零改动**。这是不可逾越的最高准则，优先于一切其它考量：协议信封、`route`/`rpc` 命名、字段名与类型、`roomtype` 配置数组、`deskinfo` 快照结构等，必须与现有协议逐字节对齐（依据 `docs/protocol/`）。本设计的所有取舍都不得违反此准则。

### 0.1 协议单一信息源（SSOT）

`docs/protocol/`（已经源码交叉审计校准的 8 篇）是**协议与数据结构的唯一权威来源**。本设计文档与后续实施计划：

- **只引用、不复制**：涉及具体 rpc、字段名、信封、`roomtype`/`deskinfo` 结构时，一律以「见 `docs/protocol/<章节>`」方式**引用**，不在设计/计划文档里内联复制协议细节。这样后续修订 `docs/protocol` 时，**无需回改本设计与实施计划**。
- **代码层落地**：框架 `protocol/` 层的 TS 类型是 `docs/protocol` 的**机器可读镜像**，二者须保持一致；协议变更先改 `docs/protocol`，再同步 `protocol/` 类型。

### 0.2 不得继承原项目的源码 bug

原 H5 模板存在已知源码 bug（见 `docs/protocol` 中 🐛 标注，如 `can_award` 接收函数缺失、小程序 deeplink `checkType` 误接白名单等）。这些功能在当前业务中已废弃，**协议层无需复刻其错误行为**；但新前端实现时须**主动规避**——按正确的协议语义实现，不得因照搬原项目逻辑而把同类缺陷带入新前端。

## 1. 目标与非目标

### 目标
1. **框架现代化**：TypeScript、响应式状态、编译期协议校验、高性能、高可扩展。
2. **框架与子游戏零耦合**：依赖单向，框架不感知任何子游戏；子游戏只通过受限边界与框架交互。
3. **框架更新方便传播**：框架改代码或界面后，所有子游戏无需「拷贝/同步」即可获得更新。
4. **消灭旧架构痛点**：旧架构模板与子游戏一对一、开发新子游戏需拷贝整份模板、更新极繁琐。

### 非目标
- 不做运行时大厅聚合 / 子游戏热插拔（部署形态为「各子游戏独立构建发布独立包」）。
- 本期不重写服务器、不改协议。

### 关键决策记录
| 维度 | 决策 |
|---|---|
| 部署形态 | 各子游戏独立构建发布独立包，但共享同一份框架源（非运行时大厅） |
| 框架边界 | 逻辑 + 平台界面（Prefab/场景/图集）+ 可换肤主题 |
| 仓库组织 | Monorepo + 符号链接（junction）共享框架 |
| YouleNexus 角色 | 框架本体的开发/演示/回归宿主工程 |
| 换肤机制 | 配置 + 资源覆盖为主，插槽为辅 |
| 新建子游戏 | 脚本从「种子工程模板」全自动克隆 |
| Cocos 版本 | 全 monorepo 统一，升级即协调发布 |

## 2. Monorepo 布局与「框架更新即时传播」

### 物理布局
```
cocoscreator_projects/
├─ YouleNexus/                    # 框架宿主工程（开发 + 演示 + 回归测试框架本体）
│  └─ assets/
│     ├─ framework/               # ★框架本体（唯一真源，被各子游戏 junction 引用）
│     │  ├─ core/  net/  protocol/  platform/  ui/  sdk/
│     └─ _dev/                    # 框架自测：mock server、mock 子游戏、调试场景（不发布）
│
├─ games/                         # 各子游戏工程（每个都是独立可构建发布的 Cocos 工程）
│  ├─ <game>/
│  │  └─ assets/
│  │     ├─ framework  ──►(junction) ../../../YouleNexus/assets/framework
│  │     └─ game/                 # 子游戏私有：IGameModule 实现 + theme + override + 对局资源
│  └─ …
│
└─ templates/
   └─ game-seed/                  # 最小但完整的空 Cocos 工程种子（new-game 克隆源）
```

### 更新传播机制
- 框架只有**一份真源**（`YouleNexus/assets/framework`）。各子游戏工程的 `assets/framework` 是指向它的 **Windows junction**（`mklink /J`，免管理员）。
- 改框架代码或界面 → 同一份物理文件 → 所有子游戏工程**即时可见**，无需拷贝/同步/bump 版本。
- 资源 `.meta` 随真源共享，**UUID 全局稳定唯一**，跨工程引用不错乱；各工程仅 `library/` 编译缓存独立。
- **取舍（已确认接受）**：框架默认即时同步到所有子游戏，改框架要对所有子游戏负责（不做「子游戏锁定框架版本」）。

### 配套工程化措施
1. **`scripts/setup-links`**（Node）：junction 内容不被 git 跟踪，团队成员 clone 后跑一次，按 `games/*` 自动重建所有 junction；新建子游戏也用它接入。
2. **`.gitignore`**：忽略各子游戏的 `assets/framework`（junction 本体）、所有 `library/` `temp/` `build/`。

## 3. 框架内部分层与零耦合规则

框架 `assets/framework/` 内分 6 层，**依赖严格单向**（上层依赖下层，下层永不反向，框架永不 import 子游戏）：

```
sdk/        子游戏对接边界（子游戏只认这一层 + core 类型）
            IGameModule 接口 · 平台→子游戏回调钩子 · 暴露给子游戏的 API facade
ui/         平台界面：登录/大厅/房间/通用弹窗 Prefab+场景 · 主题/换肤系统
platform/   平台业务：响应式 Store（RoomStore=Desk / PlayerStore=C_Player / AppStore=GameData）
            + 登录/房间/重连流程编排
protocol/   协议契约：route/rpc 常量 · 收发包 TS 类型 · 平台 RPC 封装(send/handle)
net/        传输：NetClient(WebSocket) · Envelope 双层拆包 · 心跳/30s超时/重连轮询
core/       基座：EventBus · 协议类型定义 · 座位↔视图转换 · 常量/工具
```

### 对应旧架构映射（保证协议红线不破）
- `net` + `protocol` ← 旧 `09_Net` / `00_minhttp` / `02_Const`
- `platform` ← 旧 `04_Data` / `06_Player` / `07_Desk` / `12_Logic`
- `ui` ← 旧 `11_GameUI`
- `sdk` ← 旧 `01_SubGame` 钩子契约（`Game_Modify` / `02_SubGame_Input`），但反转为接口

### 零耦合三条硬规则
1. **依赖单向 + 框架不知道任何子游戏存在**：框架代码不得出现任何子游戏名/类型；子游戏通过 `sdk` 注册自己。
2. **通信只走两条道**：① 子游戏实现 `IGameModule` 被框架调用；② 子游戏通过 `sdk` facade 调用框架能力。不允许子游戏直接 import `platform`/`net` 内部实现。
3. **状态归属清晰**：框架持有 `Desk`/`C_Player`/`GameData`（响应式 Store）；子游戏持有自己的对局态（手牌/出牌/轮次）于自身命名空间，并实现 `serialize()/restore(deskinfo)` 供断线重连。

### 高扩展点
- `protocol` 用 TS 类型结构化收发包，编译期校验，对齐协议零改。
- `platform` Store 响应式驱动 UI（状态变 → UI 自动刷新），告别旧的手动刷 UI。
- 新增平台 RPC = 加一个 typed handler，不动其它层；新增子游戏 = 注册一个 `IGameModule`，框架零改动。

## 4. 数据流与 sdk 接口契约

### 一条收发包的完整流向（单条 WebSocket，平台与对局复用）
```
收包  WebSocket frame
   → net      外层拆包 + 过滤 @toconcon/@serverheartbeat + JSON.parse → Envelope{route,rpc,data}
   → Router   route ∈ {agent,room,platform} ─► protocol handler ─► 更新 platform Store ─► UI 响应式自动刷新
              route = <game route>          ─► sdk ─► activeGame.onReceive(rpc,data) ─► 子游戏对局态 ─► 对局UI刷新
发包  平台操作: platformApi.xxx() ─► protocol 编码 ─► net.send
      对局操作: ctx.net.send(route,rpc,data) ─► net.send   （同一条连接）
```

### 接口契约（方向已定，精确签名待后续细化）

> **说明**：以下接口的**方向与边界已确认**（子游戏被 `IGameModule` 调用、通过 `GameContext` 调用框架）；**精确的方法签名、字段、能力面将在后续专门的接口设计中细化**，本 spec 不敲死。

子游戏实现（框架调用子游戏）—— `IGameModule`（示意）：
```ts
interface IGameModule {
  readonly route: string;                  // 本游戏 game route，框架据此路由对局包
  onEnter(ctx: GameContext): void;         // 进入牌桌场景，拿到框架能力句柄
  onExit(): void;
  onReceive(rpc: string, data: any): void; // 框架派发非平台包，子游戏 switch(rpc)
  onReconnect(deskinfo: any): void;        // login 响应 isbattle==1 时恢复对局
  serialize?(): any;                       // 对局快照（可选）
  // 平台事件钩子（默认空实现，按需覆写）：onPlayerJoin/onPlayerLeave/onReady/onDissolve/onOffline/...
}
```

框架暴露给子游戏（子游戏调用框架）—— `GameContext` facade（示意）：
```ts
interface GameContext {
  net:    { send(route: string, rpc: string, data: object): void };
  room:   ReadonlyRoomStore;     // 只读 Desk
  player: ReadonlyPlayerStore;   // 只读 C_Player / 座位玩家
  ui:     PlatformUI;            // toast / dialog / 通用弹窗
  events: EventBus;
  seat:   { toView(mySeat: number, target: number): number };  // 替代旧 ChangeToStatus
}
```

关键点：子游戏拿到的是**只读 Store + 受限 facade**，不能触碰 `net`/`platform` 内部，强制零耦合。

## 5. 换肤/覆盖机制（配置 + 资源覆盖为主，插槽为辅）

子游戏所有定制都落在自己的 `game/` 私有目录，**框架真源一字节不改**——这是「换肤」与「框架可更新」共存的前提。

1. **主题配置**：每个子游戏 `game/theme.ts` 声明主色/字体/图集替换映射/关键布局参数。框架 UI 组件全部「皮肤无关」，从 `ThemeProvider` 读值渲染，不写死样式。可改范围 = 框架预留的「皮肤变量」集合。
2. **资源覆盖层**：框架加载资源统一走 `AssetResolver.load(logicalPath)`，**先查 `game/override/<logicalPath>`，命中即用，否则回退 `framework/ui/default/<logicalPath>`**。子游戏放同逻辑路径资源即可替换，无需改框架。
3. **插槽**：框架关键 Prefab 预留具名挂载点 `<Slot name="xxx">`，子游戏在注册阶段声明往该槽注入自己的 Prefab。仅用于结构级深度定制，日常换肤不碰。

**冲突与更新策略**：
- 子游戏覆盖物全在 `game/`，与框架真源物理隔离 → `git pull` 框架更新不产生资源冲突。
- 框架维护一份「**皮肤变量 + 可覆盖逻辑路径 + 插槽**」契约清单（约定即 API）；改这份契约属 breaking change，需走版本说明通知子游戏。
- **取舍（已确认接受）**：框架须主动把 UI 抽象成「皮肤无关 + 变量/覆盖点」，增加框架自身开发成本，换取零冲突换肤。

## 6. 协议红线、错误处理、测试、技术栈

### 协议红线保障（第一准则的技术落地）
- `protocol/` 用 TS 类型把每个收发包结构化（字段名/类型/`roomtype`/`deskinfo`），编译期挡住字段写错。
- `net` 支持收发包**录制/回放**：存盘真实包流，框架改版后回放比对，确保协议行为不漂移。
- 一份「协议一致性测试」对照 `docs/protocol/` 各章，作为框架 CI 红线门禁。

### 错误处理（高可用）
- **网络**：30s 收包超时看门狗 + 断线候选服务器轮询重连（对齐旧 `Logic`）；重连后重发 `player_login`、按 `isbattle` 走 `onReconnect`。
- **故障隔离**：子游戏 `onReceive`/钩子用 try-catch 包裹，子游戏抛错不拖垮框架（平台连接与大厅存活），错误进统一日志。
- **资源**：`AssetResolver` 覆盖缺失 → 回退默认 → 仍缺 → 占位资源 + 告警，不黑屏。

### 测试（依托 YouleNexus 宿主工程）
- `YouleNexus/assets/_dev/` 挂 **mock server + mock 子游戏**，独立跑通登录/大厅/房间/对局/重连全流程，作为框架回归基准。
- `core/net/protocol` 纯逻辑做单元测试（拆包、心跳、编解码、座位换算）。
- 子游戏可对自己的 `IGameModule` 单测（喂 rpc 包断言对局态），不依赖真服务器。

### 技术栈
- **TypeScript**（Cocos 3.8 标配）；轻量**响应式 Store**（自研薄封装或极小库，避免重依赖）；不引大型框架，保证高性能/低耦合。

## 7. 新建子游戏流程（脚本从种子工程全自动克隆）

> 事实：Cocos Creator 无官方 CLI 凭空生成全新工程，工程须从一份已有工程复制而来。故采用「种子工程模板」克隆。

仓库维护 `templates/game-seed/`——最小但完整的 Cocos 工程，预配统一引擎版本、构建平台设置、屏幕适配、引擎模块裁剪。

```
scripts/new-game <name>
  1. 复制 templates/game-seed/  →  games/<name>/
  2. 改 package.json 的 name；重新生成 project uuid
  3. 删 library/ temp/（首次打开由编辑器重建）
  4. 建 assets/framework junction → 指向 YouleNexus 真源
  5. 铺 assets/game/ 骨架：IGameModule 空实现 + theme.ts + override/ 目录（新资源分配全新 meta uuid）
  6. 打印「用 Cocos Creator 打开 games/<name>」
```

- 复制的只是**极薄的空工程外壳**（不含框架，框架靠 junction），与旧架构「拷贝整份模板+逻辑」有本质区别。
- 种子工程需随 Cocos 版本升级维护一次；克隆时正确重置 project/资源 uuid（实现时按 3.8 实际字段验证）。

## 8. Cocos 版本升级

### 根本约束（已确认接受）
framework 真源含**带版本的序列化资源**（`.prefab`/`.scene`/`.meta`）与按某版引擎 API 写的脚本，且被多工程 junction 共享同一份物理文件。Cocos 跨版本资源格式/meta/API 可能不兼容。故：

> **所有共享 framework 的工程，Cocos 版本必须统一，不能分叉。** 这是 symlink 共享资源换「即时同步」的代价。引擎版本声明于各工程 `package.json` 的 `creator.version`。

### 升级标准流程（一次「协调发布」，在 git 升级分支上做）
```
1. 框架宿主先行：用新版 Cocos 打开 YouleNexus → 执行工程迁移 → 跑 _dev mock 回归，确认框架在新版正常
2. 升种子工程：templates/game-seed 的 creator.version 同步升新版（新子游戏天然新版，零额外操作）
3. 逐个升子游戏：每个 games/<name>
     ① 改 package.json 的 creator.version → 新版
     ② 用新版 Cocos Creator 打开，让编辑器执行迁移（library 重建、按新版重新导入 framework 资源）
     ③ 跑该子游戏回归
4. 全部子游戏验证通过 → 合并升级分支
```
第 3 步「迁移」是编辑器行为，无法纯脚本完成——每个工程都需用新版编辑器打开一次。

### 工具化与防错
- `scripts/check-cocos-version`：扫描 `games/*` 与 YouleNexus 的 `creator.version` 是否一致，不一致告警；接进 `setup-links` 与 CI，防止误用旧版打开改写资源。
- `scripts/bump-cocos <version>`：批量改各工程 `package.json` 版本字段（不替代编辑器迁移）。
- 版本粒度：补丁级（3.8.8→3.8.9）通常资源兼容、风险低；跨次版本/大版本（3.8→3.9）走完整迁移回归。

## 9. 待后续细化项（不阻塞本设计）
1. **`IGameModule` / `GameContext` 精确签名**：方法集、字段、能力面（是否含录像/语音/AI 托管等通用能力）——专门的接口设计轮次敲定。
2. **皮肤变量 / 可覆盖逻辑路径 / 插槽 契约清单**：框架 UI 抽象时逐项确定并文档化。
3. **响应式 Store 选型**：自研薄封装 vs 极小第三方库。
4. **种子工程的 uuid 重置细节**：按 Cocos 3.8.8 实际字段验证 project 与资源 uuid 的生成。
5. **协议层 TS 类型**：依 `docs/protocol/` 逐章把收发包结构落为 interface。

## 10. 风险与缓解
| 风险 | 缓解 |
|---|---|
| junction 不被 git 跟踪，团队成员环境缺链接 | `setup-links` 一键重建；文档与 CI 校验 |
| Cocos 版本误分叉导致共享资源损坏 | `check-cocos-version` 告警 + 升级走协调发布流程 |
| 框架改动波及全部子游戏 | 框架 CI 回归 + 协议一致性门禁；breaking change 走版本说明 |
| 皮肤变量预留不足，子游戏被迫改框架 | 维护契约清单，深度定制走插槽；按需扩充变量 |