From b59a6f9ca554cddb3e1de00d930be3e3e9abfac1 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Mon, 6 Jul 2026 21:52:39 +0800 Subject: [PATCH] =?UTF-8?q?=E5=89=8D=E7=AB=AF=E8=A7=84=E8=8C=83=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E4=B8=A4=E6=9D=A1=EF=BC=9A=E9=87=8D=E8=BF=9E=E5=8D=B3?= =?UTF-8?q?=E9=87=8D=E7=94=BB=EF=BC=88=E4=B8=A4=E5=9C=BA=E6=99=AF=EF=BC=89?= =?UTF-8?q?+=20UI=20=E7=BB=84=E4=BB=B6=E4=B8=93=E8=81=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 重连处理规范（04 §3.3 详解 / 05 §6 红线 / README 红线速查 / 05 §11 审查表）： 前端必须同时处理「断线重连」与「硬刷新·页面重载」两种恢复场景；本质是 恢复数据 → 逐个调各 UI 组件 setXxx/refreshXxx 恢复数据与界面状态，复用 同一条重画路径，绝不为重连单写一套渲染。 - UI 组件专职（05 §9 红线 / README 红线速查 / 05 §11 审查表）：每个界面的 数据与渲染只由其对应 UI 组件实现；别的模块要改/刷该界面一律调组件公开 接口，禁止在别处重复实现重叠或类似的界面逻辑（否则多份状态源，重连/刷新 必然不一致）。 - 两条同时进 client README 红线速查（@import 常驻层），使其每次会话在上下文。 - 未改任何小节标题；链接/锚点审计通过。 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/client/development-guide/04-网络对接与启动编排.md | 7 ++++++- docs/client/development-guide/05-开发规范与红线.md | 5 ++++- docs/client/development-guide/README.md | 2 ++ 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/client/development-guide/04-网络对接与启动编排.md b/docs/client/development-guide/04-网络对接与启动编排.md index dd42571..d42a277 100644 --- a/docs/client/development-guide/04-网络对接与启动编排.md +++ b/docs/client/development-guide/04-网络对接与启动编排.md @@ -87,7 +87,12 @@ Game_Modify.StartWar = function (_msg) { ### 重连（Reconnect）= 重画 -重连入口拿到服务端 `get_deskinfo` 的完整快照，交由新架构的重连处理**据本地数据重建整个界面**。重连与“切 app 重画”应复用同一条重画路径——**任何时候执行重画函数都能还原正确界面**（如网页刷新）。这与「数据优先、表现延后」一脉相承：界面永远能从数据无歧义地重建。 +前端**必须同时处理两种恢复场景**，二者本质相同、复用同一条重画路径： + +- **断线重连**：`Game_Modify.Reconnect` 拿到服务端 `get_deskinfo` 的完整快照，交给新架构的重连处理。 +- **硬刷新 / 页面重载**：浏览器刷新后从零重启，同样要能还原到当前对局界面。 + +**重连处理的本质 = 恢复数据 → 恢复界面**：先据快照把各组件的 `this.data` 恢复齐，再逐个调用各 UI 组件的 `setXxx`/`refreshXxx`（或组件总 `refresh()`）据数据重建界面与交互状态。**绝不为重连单写一套渲染**——它复用「组件数据自持 + set-refresh」范式（见 02 §3、05 §6）的同一条重画路径，因此**任何时候执行重画都能从数据无歧义地还原正确界面**。这与「数据优先、表现延后」一脉相承。 **红线**：受限文件 `Game_Modify.*` 里**只接不写**，业务逻辑全部在新架构 handler 中。 diff --git a/docs/client/development-guide/05-开发规范与红线.md b/docs/client/development-guide/05-开发规范与红线.md index b5cacbe..dfc9d2d 100644 --- a/docs/client/development-guide/05-开发规范与红线.md +++ b/docs/client/development-guide/05-开发规范与红线.md @@ -74,7 +74,7 @@ - **服务端权威**：所有核心运算与胜负裁定以服务端为准、数据以服务端为权威；前端只做界面展示与玩家交互，本地数据仅为「渲染副本」，不做权威计算。 - **组件数据自持 + set-refresh**：组件（及其下每个「零件 UI」）的自有数据集中在 `this.data`，**不散落**各处；每个 UI 都有 `setXxx`（只写数据）/`refreshXxx`（只据数据画界面）成对方法，组件另有总 `refresh()` 据 `this.data` 重建整块界面（见 02）。 - **收包节奏**：**先 `setXxx` 写数据 →（必要时 `refresh` 刷静态界面）→ 再播动画 → 动画回调里只刷新界面**；动画的开始/结束/出错等生命周期回调里**绝不设置核心数据**，动画期间**不改数据**。 -- **重画随时可用**：任何时候调 `refresh` 都能据 `this.data` 重建正确界面（网页刷新/断线重连/切 app 复用同一路径，不为重连单写一套渲染）。 +- **重画随时可用（断线重连 + 硬刷新都要处理）**：重连/页面重载的本质是**恢复数据 → 调各 UI 组件 `setXxx`/`refreshXxx` 恢复数据与界面状态**；任何时候调 `refresh` 都能据 `this.data` 重建正确界面（断线重连、硬刷新/网页重载、切 app 复用**同一条**重画路径，不为重连单写一套渲染，详见 04 §3.3）。 - **动画是体验层**：开发阶段可**先不做动画**只保证静态界面正确；即使动画缺失/卡住/播错，数据、逻辑与界面仍正确、互不影响。 --- @@ -99,6 +99,7 @@ ## 9. 模块职责边界 - 一个职能只在一个模块实现，其他模块**调用而非重造**：渲染找 `SpriteManager`、动画找 `AnimationManager`（及游戏动画封装）、音频找游戏音频管理、Spine 找 `SpineMgr`（及 Spine 回调分发）、发包找语义化发包封装、收包分发找收包分发器。 +- **UI 组件专职自己的界面**：每个界面的数据与渲染**只由其对应 UI 组件实现**，组件对外提供 `setXxx`/`refreshXxx` 与语义化公开方法。别的模块（controllers/managers/其他组件）要改动或刷新某界面，一律**调用该组件的公开接口**，**禁止**在别处重复实现重叠或类似的界面数据/渲染逻辑（否则同一界面出现多份状态源，重连/刷新时必然不一致）。 - 写代码前先问“这段属于谁的职责”，属于别人就调用它，不在本模块复制一份近似实现。 --- @@ -126,6 +127,8 @@ | 成败 | 只认 `data.success`，禁 `status` 兜底 | | 收发包 | 发走语义化发包封装、收走收包分发器；业务不进 `Game_Modify` | | 职责 | 一职能一模块，调用不重造 | +| UI 职责 | 每个界面的数据与渲染只在其 UI 组件实现；别处调组件接口，不重叠/重造 | +| 重连 | 断线重连 + 硬刷新都要处理；本质=恢复数据→各组件 set-refresh；复用同一重画路径 | --- diff --git a/docs/client/development-guide/README.md b/docs/client/development-guide/README.md index c2e707e..c84aaf8 100644 --- a/docs/client/development-guide/README.md +++ b/docs/client/development-guide/README.md @@ -64,7 +64,9 @@ BaseComponent / UIManager（ui，组件化与场景） ← gameabc-framework（ - **服务端权威、前端只展示**：核心运算与胜负裁定以服务端为准、数据以服务端为权威；前端只做界面展示与玩家交互，本地数据仅为渲染副本，不做权威计算。 - **组件走 BaseComponent**：UI 组件继承 `BaseComponent`，事件用 `this.addEventListener` 注册（`destroy()` 自动清理，防泄漏）；动态精灵/定时器在 `onDestroy` 清理。 - **组件数据自持 + set-refresh**：组件自有数据集中 `this.data`；每个 UI/零件有 `setXxx`(只写数据)/`refreshXxx`(只据数据画)对，组件有总 `refresh()` 可据数据重建界面。 +- **UI 组件专职自己的界面**：每个界面的数据与渲染只由其对应 UI 组件实现；别的模块要改/刷该界面一律**调该组件的公开接口**（`setXxx`/`refreshXxx`/语义方法），**禁止**在别处重复实现重叠或类似的界面数据/渲染逻辑。 - **数据优先、表现延后**：收到推送先 `setXxx` 写数据、再播动画；动画的开始/结束/出错回调里**只刷界面、不写核心数据**。即使动画缺失/卡住/出错，数据、逻辑、界面仍正确、互不影响。 +- **重连即重画（断线重连 + 硬刷新都要处理）**：重连/页面重载的本质是**恢复数据 → 调各 UI 组件 set-refresh 恢复数据与界面状态**，复用同一条重画路径，不为重连单写一套渲染（详见 04 §3.3、05 §6）。 - **成败只认 `data.success`**：前端一律 `if (!data.success)` 判成败，**不**用 `status`/`code`，**不**写 `status` 兼容兜底。 - **收发包走统一通道**：发包经统一发送封装（底层 `RpcHelper` 自动注入平台字段），收包统一分发（一 rpc 一处理器）；业务逻辑放处理器，**不**写进 `Game_Modify.*`。 - **shared 只读**：`01_SubGame/codes/shared/` 是服务端 `shared/` 的同步副本，**不在前端改**，改服务端权威源后跑同步脚本。