youle_framework/docs/games/engineering/一页纸总则.md

工程与架构通则 · 一页纸

本文是与平台无关的工程方法论那一页：七大总则 + 适用边界。 它由 CLAUDE.md 通过 @import 常驻每次会话上下文；总则以本文为权威。 文档导航、各篇主题、与既有文档的关系见 README。

---

一页纸：七大总则

1. 单一权威数据源（SSOT）：同一业务数据只有一个计算/写入处，其他只读；缺失即显式失败，不兜底掩盖。
2. 单向依赖：分层自上而下依赖，稳定的被依赖、易变的作依赖方；禁止环形依赖。
3. 职责单一、边界清晰：一个职能只在一个模块实现，别处调用而非重造。
4. 关注点分离：决策与机制分离、数据与表现分离、编排与算法分离。
5. 对扩展开放、对修改封闭（OCP）：用注册/策略/管线加能力，不改动已稳定的核心。
6. 配置优先于硬编码：会变、复用、无语义的值一律外提为常量/配置，用数据驱动行为。
7. 显式失败优于隐式兜底：关键路径缺数据就报错/返回 null，把问题暴露在最近处。

这七条互相支撑：SSOT + 显式失败保正确，单向依赖 + 职责单一 + 关注点分离保清晰， OCP + 配置化保可演进。任何设计取舍，回到这七条对照。

---

适用范围与边界

• 适用：子游戏自身的前后端业务代码（玩法逻辑、对局编排、收发包处理、表现层、共享算法）。
• 不覆盖：平台框架代码（不可改）、平台接入契约（见各端 development-guide/）。
• 与硬约束的关系：ES5、require 守卫、可编辑范围、成败标志 data.success 等硬红线仍以 development-guide/ 为准；本套是方法论层，与之互补不冲突。