文档修复：校正开发指南编号与失效交叉引用
- CLAUDE.md：前端指南编号由「01→05」订正为「01→06」（06 子游戏接入模式实存且已被本文件他处引用）；删除已过期的 server/docs 旧副本警告（该旧副本已从工作树删除）。 - 两份 development-guide README + 各章节正文：将旧路径 server/docs/development-guide、client/docs/development-guide 统一订正为 docs/server、docs/client；docs/engineering 订正为 docs/games/engineering。 - 客户端 README 阅读顺序补齐缺失的 06 篇。 - 服务端 README 移除指向不存在的 docs/important/server 的条目。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -10,8 +10,8 @@
|
||||
|
||||
## 这套文档写给谁
|
||||
|
||||
- **新接手子游戏前端的开发者**：先读 01、02 建立全局认知，再按 03、04 动手，05 随时回查。
|
||||
- **正在开发/维护某子游戏前端的开发者**：02–05 是日常手册与红线。
|
||||
- **新接手子游戏前端的开发者**：先读 01、02 建立全局认知，再按 03、04、06 动手，05 随时回查。
|
||||
- **正在开发/维护某子游戏前端的开发者**：02–06 是日常手册与红线。
|
||||
- **做代码审查的人**：05 是审查清单来源。
|
||||
|
||||
## 阅读顺序
|
||||
@@ -20,12 +20,13 @@
|
||||
|----|------|--------------|
|
||||
| 00 | 本文 README | 这套文档是什么、怎么读、红线速查 |
|
||||
| 01 | [01-前端架构与运行环境.md](./01-前端架构与运行环境.md) | 双运行时/ES5、平台/框架/子游戏三层、新旧架构并存、目录与加载顺序 |
|
||||
| 02 | [02-渲染与UI组件体系.md](./02-渲染与UI组件体系.md) | 精灵 ID 体系、SpriteManager 分层、资源常量组织、BaseComponent 组件化、UIManager 场景、动态列表 |
|
||||
| 02 | [02-渲染与UI组件体系.md](./02-渲染与UI组件体系.md) | 精灵 ID 体系、SpriteManager 分层、资源常量组织、BaseComponent 组件化、组件数据/set-refresh 范式、UIManager 场景、动态列表 |
|
||||
| 03 | [03-事件·动画·音频·Spine.md](./03-事件·动画·音频·Spine.md) | EventBus、AnimationManager+配置、AudioManager+音效资源、SpineMgr 全链路 |
|
||||
| 04 | [04-网络对接与启动编排.md](./04-网络对接与启动编排.md) | 发包链路（RpcHelper 注入平台字段）、收包统一分发、新旧架构对接边界、启动编排、处理器/管理器职责 |
|
||||
| 05 | [05-开发规范与红线.md](./05-开发规范与红线.md) | 可编辑范围、ES5、框架中立、常量集中、组件生命周期、data.success、模块职责、测试 |
|
||||
| 05 | [05-开发规范与红线.md](./05-开发规范与红线.md) | 可编辑范围、ES5、框架中立、常量集中、组件生命周期、服务端权威/组件数据/表现延后、data.success、模块职责、测试 |
|
||||
| 06 | [06-子游戏接入模式与Hooks外置.md](./06-子游戏接入模式与Hooks外置.md) | 内联模式 vs Hooks 外置模式、三个契约文件退化为转发壳、SubGameHooks 委托、subgame-entry 模板 |
|
||||
|
||||
建议第一次**从 01 顺序读到 05**；之后把 02–05 当手册随用随查。
|
||||
建议第一次**从 01 顺序读到 06**；之后把 02–06 当手册随用随查。
|
||||
|
||||
---
|
||||
|
||||
@@ -60,8 +61,10 @@ BaseComponent / UIManager（ui，组件化与场景） ← gameabc-framework（
|
||||
- **框架游戏中立**：`gameabc-framework/` 内**不得**出现任何具体玩法逻辑或专属常量；玩法专属的事件/资源/配置一律定义在子游戏侧（如玩法事件在子游戏的事件常量文件里追加到 `EventBus.Events`）。
|
||||
- **精灵只走 SpriteManager**：UI 代码**禁止**直接调 `GameABCUtils` 或引擎原生 API；ID 必须落在规定范围（精灵 1001–3000、群组 ≥201、图层 101–200/弹窗 301–400，另有 501–600、701+ 备用段，框架保留 1–1000 及 3001+ 等交替段）。
|
||||
- **常量集中、禁硬编码**：精灵 ID/图片资源 ID/坐标尺寸/动画时长/音效 ID 一律定义在对应常量文件，业务代码引用，**不内联裸值**。
|
||||
- **服务端权威、前端只展示**：核心运算与胜负裁定以服务端为准、数据以服务端为权威；前端只做界面展示与玩家交互，本地数据仅为渲染副本，不做权威计算。
|
||||
- **组件走 BaseComponent**：UI 组件继承 `BaseComponent`，事件用 `this.addEventListener` 注册（`destroy()` 自动清理，防泄漏）；动态精灵/定时器在 `onDestroy` 清理。
|
||||
- **数据优先、表现延后**：收到推送先改数据模型，再播动画，动画回调里刷新静态界面；动画期间**不改数据**。即使不播动画，重画函数也能据本地数据还原正确界面。
|
||||
- **组件数据自持 + set-refresh**：组件自有数据集中 `this.data`；每个 UI/零件有 `setXxx`(只写数据)/`refreshXxx`(只据数据画)对，组件有总 `refresh()` 可据数据重建界面。
|
||||
- **数据优先、表现延后**：收到推送先 `setXxx` 写数据、再播动画；动画的开始/结束/出错回调里**只刷界面、不写核心数据**。即使动画缺失/卡住/出错，数据、逻辑、界面仍正确、互不影响。
|
||||
- **成败只认 `data.success`**：前端一律 `if (!data.success)` 判成败，**不**用 `status`/`code`，**不**写 `status` 兼容兜底。
|
||||
- **收发包走统一通道**：发包经统一发送封装（底层 `RpcHelper` 自动注入平台字段），收包统一分发（一 rpc 一处理器）；业务逻辑放处理器，**不**写进 `Game_Modify.*`。
|
||||
- **shared 只读**：`01_SubGame/codes/shared/` 是服务端 `shared/` 的同步副本，**不在前端改**，改服务端权威源后跑同步脚本。
|
||||
@@ -70,6 +73,7 @@ BaseComponent / UIManager（ui，组件化与场景） ← gameabc-framework（
|
||||
|
||||
## 与既有文档的关系
|
||||
|
||||
- 服务端的对应文档在 [`server/docs/development-guide/`](../../../server/docs/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。
|
||||
- 服务端的对应文档在 [`docs/server/development-guide/`](../../server/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。
|
||||
- 子游戏前端各层可能另有局部说明文档；本套是总纲，与之不冲突时以本套的通用原则为准。
|
||||
- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/games/engineering/`](../../games/engineering/)：本套讲前端接入与红线，`engineering/` 讲前后端通用的设计方法论，互补阅读。
|
||||
</content>
|
||||
|
||||
Reference in New Issue
Block a user