docs(spec): 补充协议 SSOT 引用原则与原项目 bug 规避

- 0.1 协议单一信息源:设计/计划只引用 docs/protocol 章节、不内联复制,
  协议修订无需回改设计与实施计划;framework/protocol TS 类型为其机器镜像
- 0.2 不继承原项目源码 bug:按正确协议语义实现,主动规避同类缺陷

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-28 11:37:32 +08:00
co-authored by Claude Opus 4.8
parent 08640ca89a
commit 17a82eb5bf
@@ -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. 目标与非目标
### 目标