diff --git a/CLAUDE.md b/CLAUDE.md index 5371f01..914eb03 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -84,7 +84,15 @@ server/<游戏容器目录>/<游戏>/ ← 子游戏接入后**唯一 ### 文档（改动前先读） -`docs/client/development-guide/`与`docs/server/development-guide/`（按 01→05/04 编号）是本项目遵循的权威、项目专属开发指南——改哪块就读对应编号的文档，而不是从代码反推约定。`docs/games/engineering/` 是位于两者之上的、与平台无关的工程方法论层（单一权威数据源 SSOT、单向依赖、职责单一、对扩展开放对修改封闭 OCP、配置优先于硬编码、显式失败优于隐式兜底）。 +`docs/client/development-guide/`（01→06）与 `docs/server/development-guide/`（01→04）是本项目遵循的权威、项目专属开发指南——改哪块就读对应编号的文档，而不是从代码反推约定。`docs/games/engineering/`（01→03）是位于两者之上的、与平台无关的工程方法论层（单一权威数据源 SSOT、单向依赖、职责单一、对扩展开放对修改封闭 OCP、配置优先于硬编码、显式失败优于隐式兜底）。**三者互补不冲突：engineering 讲「该怎么设计、怎么长久演进」，dev-guide 讲「平台怎么接、红线是什么」；ES5/`require` 守卫/可编辑范围/`data.success` 等硬红线冲突时一律以 dev-guide 为准。** + +各编号对应主题（改哪块查哪篇）： + +| 文档 | 编号与主题 | +|---|---| +| `client/development-guide/` | 01 前端架构与运行环境 · 02 渲染与UI组件体系 · 03 事件·动画·音频·Spine · 04 网络对接与启动编排 · 05 开发规范与红线 · 06 子游戏接入模式与Hooks外置 | +| `server/development-guide/` | 01 服务端环境与框架基础 · 02 子游戏接入与开发流程 · 03 数据收发与通信协议 · 04 开发规范与红线 | +| `games/engineering/` | 01 架构总则与分层 · 02 可扩展性与配置化 · 03 数据权威·错误处理·演进 | 两套文档中反复强调的硬性规则（文档记载均对应过真实事故）： - 全面严格 ES5（`var`/`function`，继承用 `Object.create`；禁止 `let/const`/箭头函数/模板字符串/`class`/解构/`Promise`）。 diff --git a/docs/client/development-guide/04-网络对接与启动编排.md b/docs/client/development-guide/04-网络对接与启动编排.md index 25167a6..0e8d5ec 100644 --- a/docs/client/development-guide/04-网络对接与启动编排.md +++ b/docs/client/development-guide/04-网络对接与启动编排.md @@ -2,7 +2,7 @@ 本篇讲**前端怎么和服务端打通、一局怎么启动**：发包链路、收包分发、新旧架构的对接边界、成败判定、启动顺序与 controllers/managers 的职责。 -> **想看前后端端到端全链路**（一个包从前端出发 → 服务端三层路由/handler → 推回前端分发的完整往返、及各步在谁的哪个文件）见服务端 [`server/docs/development-guide/03 §6`](../../../server/docs/development-guide/03-数据收发与通信协议.md#6-端到端收发全链路前后端对照)。本篇聚焦**前端这一侧**的收发细节。 +> **想看前后端端到端全链路**（一个包从前端出发 → 服务端三层路由/handler → 推回前端分发的完整往返、及各步在谁的哪个文件）见服务端 [`docs/server/development-guide/03 §6`](../../server/development-guide/03-数据收发与通信协议.md#6-端到端收发全链路前后端对照)。本篇聚焦**前端这一侧**的收发细节。 --- @@ -98,7 +98,7 @@ Game_Modify.StartWar = function (_msg) { ## 4. 成败判定：只认 `data.success` -> 与服务端 [`server/docs/development-guide/03`](../../../server/docs/development-guide/03-数据收发与通信协议.md) 同一条协议。 +> 与服务端 [`docs/server/development-guide/03`](../../server/development-guide/03-数据收发与通信协议.md) 同一条协议。 前端 RPC 没有“同步返回”，操作结果由服务端**后续主动推送**告知。判成败的唯一权威是推送 `data` 里的 **`success`**： diff --git a/docs/client/development-guide/05-开发规范与红线.md b/docs/client/development-guide/05-开发规范与红线.md index 1d38d7a..4e2285d 100644 --- a/docs/client/development-guide/05-开发规范与红线.md +++ b/docs/client/development-guide/05-开发规范与红线.md @@ -92,7 +92,7 @@ - **`shared/` 是子游戏自己的游戏逻辑，与平台无关**：存放本玩法**前后端必须算出完全一致**的纯逻辑（胡牌/听牌/比精/牌型/计分/规则常量等），前端用于即时表现与预校验，服务端做权威裁定。它不是平台代码，平台既不提供也不感知。 - `01_SubGame/codes/shared/` 是服务端 `server/<游戏容器目录>/<游戏>/shared/` 的**同步副本**，前端**只读**（脚本生成）。 - 改共享算法只改服务端权威源，再运行同步脚本覆盖前端副本；**禁止直接编辑前端 `codes/shared/`**。 -- 逻辑同源不改变数据权威：前端 `shared/` 算的是表现/预判，最终以服务端为准（数据优先、表现延后，见 §6）。详见服务端 [`server/docs/development-guide/04 §8`](../../../server/docs/development-guide/04-开发规范与红线.md#8-shared-文件同步流程)。 +- 逻辑同源不改变数据权威：前端 `shared/` 算的是表现/预判，最终以服务端为准（数据优先、表现延后，见 §6）。详见服务端 [`docs/server/development-guide/04 §8`](../../server/development-guide/04-开发规范与红线.md#8-shared-文件同步流程)。 --- diff --git a/docs/client/development-guide/README.md b/docs/client/development-guide/README.md index 45badff..def4f01 100644 --- a/docs/client/development-guide/README.md +++ b/docs/client/development-guide/README.md @@ -24,8 +24,9 @@ | 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、模块职责、测试 | +| 06 | [06-子游戏接入模式与Hooks外置.md](./06-子游戏接入模式与Hooks外置.md) | 内联模式 vs Hooks 外置模式、三契约文件可改性、退化为纯转发壳 + SubGameHooks 委托、subgame-entry 模板 | -建议第一次**从 01 顺序读到 05**；之后把 02–05 当手册随用随查。 +建议第一次**从 01 顺序读到 05**；之后把 02–05 当手册随用随查。06 在接入新游戏或迁移到 Hooks 外置模式时选读。 --- @@ -72,7 +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/engineering/`](../../../docs/engineering/)：本套讲前端接入与红线，`engineering/` 讲前后端通用的设计方法论，互补阅读。 +- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/games/engineering/`](../../games/engineering/)：本套讲前端接入与红线，`engineering/` 讲前后端通用的设计方法论，互补阅读。 diff --git a/docs/games/engineering/03-数据权威·错误处理·演进.md b/docs/games/engineering/03-数据权威·错误处理·演进.md index 10bf775..5980fa3 100644 --- a/docs/games/engineering/03-数据权威·错误处理·演进.md +++ b/docs/games/engineering/03-数据权威·错误处理·演进.md @@ -1,7 +1,7 @@ # 03 · 数据权威 · 错误处理 · 演进 本篇是**正确性**的地基：数据从哪来、错了怎么暴露、代码怎么随规则长大而不腐化。 -数据权威部分在 `.github/copilot/skills/data-authority-principle.md` 基础上，扩展到**前后端全景**。 +数据权威部分在项目既有的「数据权威原则」基础上，扩展到**前后端全景**。 --- diff --git a/docs/games/engineering/README.md b/docs/games/engineering/README.md index c14bb14..2b3029d 100644 --- a/docs/games/engineering/README.md +++ b/docs/games/engineering/README.md @@ -59,8 +59,6 @@ | 文档 | 定位 | |------|------| | 各端 `development-guide/` | 平台接入 + 工程红线（**能跑、合规**） | -| `docs/architecture/` | **本系统**的具体架构说明（是什么样） | -| `.github/copilot/skills/data-authority-principle.md` | 数据权威原则（本套 03 篇在其上扩展到前后端） | -| **本套 `docs/engineering/`** | **平台无关的通用工程与架构规范**（该怎么设计） | +| **本套 `docs/games/engineering/`** | **平台无关的通用工程与架构规范**（该怎么设计） | > 具体命名（模块名/文件名/方法名）在本套文档里多为**示例、可自定**；约束的是**做法与结构**，不是具体名字。 diff --git a/docs/server/development-guide/03-数据收发与通信协议.md b/docs/server/development-guide/03-数据收发与通信协议.md index 7b6ead7..fbfe654 100644 --- a/docs/server/development-guide/03-数据收发与通信协议.md +++ b/docs/server/development-guide/03-数据收发与通信协议.md @@ -46,7 +46,7 @@ ### 1.2 发包必须自带前端界面所需的全部核心数据 -**前端以服务端数据为权威——只做界面展示与交互、不做权威计算**（见 [`client 05`](../../../client/docs/development-guide/05-开发规范与红线.md)）。推论落到服务端：**每个下发包都必须携带前端渲染/刷新该界面所需的全部核心数据**，让前端「据包写入数据 → 直接刷新出界面」，而**不需要前端自行推算、补全或兜底**。 +**前端以服务端数据为权威——只做界面展示与交互、不做权威计算**（见 [`client 05`](../../client/development-guide/05-开发规范与红线.md)）。推论落到服务端：**每个下发包都必须携带前端渲染/刷新该界面所需的全部核心数据**，让前端「据包写入数据 → 直接刷新出界面」，而**不需要前端自行推算、补全或兜底**。 - **界面要用的字段都要发全**：凡界面要显示、或前端 set/refresh 要用到的核心字段（出了什么牌、轮到谁、各家剩余张数、手牌/副露、分数/比分、倒计时锚点、庄家/座位、各类状态标志……）都要放进 `data`，不能让前端"猜"或本地推算权威结果。 - **漏发是服务端的缺陷，不许前端补**：前端遵循数据权威原则——权威字段缺失应显式报错/留空、不用 `|| 0`/`|| []` 兜造（见 client 05）。所以服务端漏发 = 前端界面缺数据，**修在服务端发包处，不在前端补洞**。 @@ -253,7 +253,7 @@ if (!data.success) { /* 失败处理 */ return; } | 重连/中途加入 | `export.get_deskinfo` 的返回 | `Game_Modify.Reconnect(_deskinfo)` → 重画 | | 对局/推送 | RPC handler 或主动推送（按 `rpc`） | 收包分发表里同名 `rpc` 的处理器 | -**改服务端下发结构 = 同步核对前端对应 `rpc` 的解析**；**新增一种推送 = 服务端选定 `rpc` + 前端在分发表加同名处理器**。任一端单方面改，另一端必按旧结构解析出错。前端侧的收发细节以 [`client/docs/development-guide/04-网络对接与启动编排`](../../../client/docs/development-guide/04-网络对接与启动编排.md) 为权威。 +**改服务端下发结构 = 同步核对前端对应 `rpc` 的解析**；**新增一种推送 = 服务端选定 `rpc` + 前端在分发表加同名处理器**。任一端单方面改，另一端必按旧结构解析出错。前端侧的收发细节以 [`docs/client/development-guide/04-网络对接与启动编排`](../../client/development-guide/04-网络对接与启动编排.md) 为权威。 --- diff --git a/docs/server/development-guide/README.md b/docs/server/development-guide/README.md index 16e219d..2e8d6cb 100644 --- a/docs/server/development-guide/README.md +++ b/docs/server/development-guide/README.md @@ -52,7 +52,7 @@ o_room.method.sendpack_toseat 按座位取连接信息(conmode/fromid) → 下 - **平台框架**负责：网络收发、应用/模块/房间/玩家对象、路由、房卡、战绩、房间生命周期。 - **子游戏**负责：玩法规则、对局状态、每个操作的处理与广播。两者通过 **export / import** 两组接口对接。 -> 上图是**入站半程**（前端 → 服务端 handler）。完整的往返链路（含服务端 `sendpack_toseat` 推回 → 前端 `Game_Modify._ReceiveData` 按 `rpc` 分发）见 [03 §6「端到端收发全链路」](./03-数据收发与通信协议.md#6-端到端收发全链路前后端对照)，前端侧细节见 [`client/docs/development-guide/04`](../../../client/docs/development-guide/04-网络对接与启动编排.md)。 +> 上图是**入站半程**（前端 → 服务端 handler）。完整的往返链路（含服务端 `sendpack_toseat` 推回 → 前端 `Game_Modify._ReceiveData` 按 `rpc` 分发）见 [03 §6「端到端收发全链路」](./03-数据收发与通信协议.md#6-端到端收发全链路前后端对照)，前端侧细节见 [`docs/client/development-guide/04`](../../client/development-guide/04-网络对接与启动编排.md)。 --- @@ -94,6 +94,6 @@ o_room.method.sendpack_toseat 按座位取连接信息(conmode/fromid) → 下 - 平台级、面向「所有子游戏」的总纲在 `docs/important/server/`（友乐框架收发包规范、子游戏开发要求）。 - 本套文档是其**落地版**：结合本仓库真实代码，给出可直接照做的接入步骤与红线，并对其中已被本项目实践修正的部分（如成败标志由 `status` 收敛为 `success`）以本套为准。 - 各子游戏内部的架构细节（模块划分、算法）仍以各自 `<游戏容器目录>/<游戏>/docs/` 为准。 -- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/engineering/`](../../../docs/engineering/)：本套讲"平台怎么接、红线是什么"，`engineering/` 讲"该怎么设计、怎么长久演进"，互补阅读。 +- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/games/engineering/`](../../games/engineering/)：本套讲"平台怎么接、红线是什么"，`engineering/` 讲"该怎么设计、怎么长久演进"，互补阅读。