From 6b00b80741adfda493ca98827990dd17bed99eb4 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Sun, 5 Jul 2026 23:25:43 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E8=B7=A8=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E9=93=BE=E6=8E=A5=E7=9A=84=E6=98=BE=E7=A4=BA=E6=96=87?= =?UTF-8?q?=E5=AD=97=E6=94=B9=E4=B8=BA=E4=BD=8D=E7=BD=AE=E6=97=A0=E5=85=B3?= =?UTF-8?q?=E5=86=99=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 链接目标本就是相对路径，但显示文字硬写了 docs/xxx/development-guide 这类绝对式路径名——目录一旦整体移动，文字即过时（链接仍可跳）。 将 10 处显示文字统一改为「篇号 + 篇名」等只依赖文档自身、不依赖 所在路径的写法（如 docs/server/development-guide/03 §6 → 03 §6「端到端收发全链路」），engineering README 自称路径同样收敛为 泛指的 engineering/。至此保持三套目录相对位置不变即无需改任何链接。 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/client/development-guide/04-网络对接与启动编排.md | 4 ++-- docs/client/development-guide/05-开发规范与红线.md | 2 +- docs/client/development-guide/README.md | 4 ++-- docs/games/engineering/README.md | 2 +- docs/server/development-guide/03-数据收发与通信协议.md | 4 ++-- docs/server/development-guide/README.md | 4 ++-- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/client/development-guide/04-网络对接与启动编排.md b/docs/client/development-guide/04-网络对接与启动编排.md index 0e8d5ec..51007c0 100644 --- a/docs/client/development-guide/04-网络对接与启动编排.md +++ b/docs/client/development-guide/04-网络对接与启动编排.md @@ -2,7 +2,7 @@ 本篇讲**前端怎么和服务端打通、一局怎么启动**：发包链路、收包分发、新旧架构的对接边界、成败判定、启动顺序与 controllers/managers 的职责。 -> **想看前后端端到端全链路**（一个包从前端出发 → 服务端三层路由/handler → 推回前端分发的完整往返、及各步在谁的哪个文件）见服务端 [`docs/server/development-guide/03 §6`](../../server/development-guide/03-数据收发与通信协议.md#6-端到端收发全链路前后端对照)。本篇聚焦**前端这一侧**的收发细节。 +> **想看前后端端到端全链路**（一个包从前端出发 → 服务端三层路由/handler → 推回前端分发的完整往返、及各步在谁的哪个文件）见服务端 [03 §6「端到端收发全链路」](../../server/development-guide/03-数据收发与通信协议.md#6-端到端收发全链路前后端对照)。本篇聚焦**前端这一侧**的收发细节。 --- @@ -98,7 +98,7 @@ Game_Modify.StartWar = function (_msg) { ## 4. 成败判定：只认 `data.success` -> 与服务端 [`docs/server/development-guide/03`](../../server/development-guide/03-数据收发与通信协议.md) 同一条协议。 +> 与服务端 [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 4e2285d..f1a823c 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）。详见服务端 [`docs/server/development-guide/04 §8`](../../server/development-guide/04-开发规范与红线.md#8-shared-文件同步流程)。 +- 逻辑同源不改变数据权威：前端 `shared/` 算的是表现/预判，最终以服务端为准（数据优先、表现延后，见 §6）。详见服务端 [04 §8 shared 文件同步流程](../../server/development-guide/04-开发规范与红线.md#8-shared-文件同步流程)。 --- diff --git a/docs/client/development-guide/README.md b/docs/client/development-guide/README.md index def4f01..c2e707e 100644 --- a/docs/client/development-guide/README.md +++ b/docs/client/development-guide/README.md @@ -73,7 +73,7 @@ BaseComponent / UIManager（ui，组件化与场景） ← gameabc-framework（ ## 与既有文档的关系 -- 服务端的对应文档在 [`docs/server/development-guide/`](../../server/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。 +- 服务端的对应文档见 [服务端开发指导文档](../../server/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。 - 子游戏前端各层可能另有局部说明文档；本套是总纲，与之不冲突时以本套的通用原则为准。 -- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/games/engineering/`](../../games/engineering/)：本套讲前端接入与红线，`engineering/` 讲前后端通用的设计方法论，互补阅读。 +- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [工程与架构通则](../../games/engineering/)：本套讲前端接入与红线，工程通则讲前后端通用的设计方法论，互补阅读。 diff --git a/docs/games/engineering/README.md b/docs/games/engineering/README.md index 2b3029d..640c28f 100644 --- a/docs/games/engineering/README.md +++ b/docs/games/engineering/README.md @@ -59,6 +59,6 @@ | 文档 | 定位 | |------|------| | 各端 `development-guide/` | 平台接入 + 工程红线（**能跑、合规**） | -| **本套 `docs/games/engineering/`** | **平台无关的通用工程与架构规范**（该怎么设计） | +| **本套 `engineering/`** | **平台无关的通用工程与架构规范**（该怎么设计） | > 具体命名（模块名/文件名/方法名）在本套文档里多为**示例、可自定**；约束的是**做法与结构**，不是具体名字。 diff --git a/docs/server/development-guide/03-数据收发与通信协议.md b/docs/server/development-guide/03-数据收发与通信协议.md index fbfe654..0c93f1e 100644 --- a/docs/server/development-guide/03-数据收发与通信协议.md +++ b/docs/server/development-guide/03-数据收发与通信协议.md @@ -46,7 +46,7 @@ ### 1.2 发包必须自带前端界面所需的全部核心数据 -**前端以服务端数据为权威——只做界面展示与交互、不做权威计算**（见 [`client 05`](../../client/development-guide/05-开发规范与红线.md)）。推论落到服务端：**每个下发包都必须携带前端渲染/刷新该界面所需的全部核心数据**，让前端「据包写入数据 → 直接刷新出界面」，而**不需要前端自行推算、补全或兜底**。 +**前端以服务端数据为权威——只做界面展示与交互、不做权威计算**（见 [前端 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` + 前端在分发表加同名处理器**。任一端单方面改，另一端必按旧结构解析出错。前端侧的收发细节以 [`docs/client/development-guide/04-网络对接与启动编排`](../../client/development-guide/04-网络对接与启动编排.md) 为权威。 +**改服务端下发结构 = 同步核对前端对应 `rpc` 的解析**；**新增一种推送 = 服务端选定 `rpc` + 前端在分发表加同名处理器**。任一端单方面改，另一端必按旧结构解析出错。前端侧的收发细节以 [前端 04 网络对接与启动编排](../../client/development-guide/04-网络对接与启动编排.md) 为权威。 --- diff --git a/docs/server/development-guide/README.md b/docs/server/development-guide/README.md index 098761a..208af44 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-端到端收发全链路前后端对照)，前端侧细节见 [`docs/client/development-guide/04`](../../client/development-guide/04-网络对接与启动编排.md)。 +> 上图是**入站半程**（前端 → 服务端 handler）。完整的往返链路（含服务端 `sendpack_toseat` 推回 → 前端 `Game_Modify._ReceiveData` 按 `rpc` 分发）见 [03 §6「端到端收发全链路」](./03-数据收发与通信协议.md#6-端到端收发全链路前后端对照)，前端侧细节见 [前端 04 网络对接与启动编排](../../client/development-guide/04-网络对接与启动编排.md)。 --- @@ -93,6 +93,6 @@ o_room.method.sendpack_toseat 按座位取连接信息(conmode/fromid) → 下 - 本套文档是平台级收发包/子游戏开发规范的**落地版**：结合本仓库真实代码，给出可直接照做的接入步骤与红线，并对其中已被本项目实践修正的部分（如成败标志由 `status` 收敛为 `success`）以本套为准。 - 各子游戏内部的架构细节（模块划分、算法）仍以各自 `<游戏容器目录>/<游戏>/docs/` 为准。 -- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/games/engineering/`](../../games/engineering/)：本套讲"平台怎么接、红线是什么"，`engineering/` 讲"该怎么设计、怎么长久演进"，互补阅读。 +- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [工程与架构通则](../../games/engineering/)：本套讲"平台怎么接、红线是什么"，工程通则讲"该怎么设计、怎么长久演进"，互补阅读。