From 17a82eb5bf483b6606736575339174ec6d408cdc Mon Sep 17 00:00:00 2001 From: Joywayer Date: Sun, 28 Jun 2026 11:37:32 +0800 Subject: [PATCH] =?UTF-8?q?docs(spec):=20=E8=A1=A5=E5=85=85=E5=8D=8F?= =?UTF-8?q?=E8=AE=AE=20SSOT=20=E5=BC=95=E7=94=A8=E5=8E=9F=E5=88=99?= =?UTF-8?q?=E4=B8=8E=E5=8E=9F=E9=A1=B9=E7=9B=AE=20bug=20=E8=A7=84=E9=81=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 0.1 协议单一信息源：设计/计划只引用 docs/protocol 章节、不内联复制， 协议修订无需回改设计与实施计划；framework/protocol TS 类型为其机器镜像 - 0.2 不继承原项目源码 bug：按正确协议语义实现，主动规避同类缺陷 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../specs/2026-06-28-cocos-framework-design.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/superpowers/specs/2026-06-28-cocos-framework-design.md b/docs/superpowers/specs/2026-06-28-cocos-framework-design.md index 4cf0a61..2fea208 100644 --- a/docs/superpowers/specs/2026-06-28-cocos-framework-design.md +++ b/docs/superpowers/specs/2026-06-28-cocos-framework-design.md @@ -11,6 +11,17 @@ 任何前端开发都必须完全遵循前后端数据包的协议与数据结构，做到**服务器零改动**。这是不可逾越的最高准则，优先于一切其它考量：协议信封、`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. 目标与非目标 ### 目标