# 子游戏前后端开发规范 · 工程与架构通则

> 本套文档总结一套**专业、成熟、平台无关**的子游戏开发规范。它不讲某个平台怎么接入，
> 而是从**架构与工程**的角度，给出前后端通用的设计原则、可扩展模式、配置化实践与反模式清单，
> 指导开发者写出**优雅、现代、易演进、少返工**的子游戏代码。

---

## 这套文档解决什么

平台接入细节（三层路由、export/import、收发包协议、ES5/require 等）已在各端
`development-guide/` 中讲清；本套文档是它们之上的**工程方法论**：

- **怎样分层**，让依赖单向、边界清晰、改一处不牵一身；
- **怎样扩展**，让新增玩法/规则/策略是"加代码"而非"改核心"；
- **怎样配置化**，把会变的东西从硬编码里拿出来，用数据驱动；
- **怎样守住数据权威**，让同一份数据只有一个来源、缺失即显式失败；
- **怎样不过度设计**，在"能扩展"与"够简单"之间拿捏。

> 一句话定位：**平台接入是"能不能跑通"，本套规范是"跑得久、改得动、错得少"。**

---

## 阅读导航

| 篇 | 文档 | 解决什么 |
|----|------|----------|
| 00 | 本文 README | 定位、适用范围、一页纸总则、与既有文档的关系 |
| 01 | [01-架构总则与分层.md](./01-架构总则与分层.md) | 七大架构总则；前后端参考分层；依赖方向与稳定依赖 |
| 02 | [02-可扩展性与配置化.md](./02-可扩展性与配置化.md) | 扩展模式（注册表/策略/管线/工厂/事件）何时用；配置化与去硬编码；避免过度设计 |
| 03 | [03-数据权威·错误处理·演进.md](./03-数据权威·错误处理·演进.md) | 数据权威（前后端）；错误处理与可观测；演进与重构；反模式与审查清单 |

---

## 一页纸：七大总则

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

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

---

## 适用范围与边界

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

## 与既有文档的关系

| 文档 | 定位 |
|------|------|
| 各端 `development-guide/` | 平台接入 + 工程红线（**能跑、合规**） |
| `docs/architecture/` | **本系统**的具体架构说明（是什么样） |
| `.github/copilot/skills/data-authority-principle.md` | 数据权威原则（本套 03 篇在其上扩展到前后端） |
| **本套 `docs/games/engineering/`** | **平台无关的通用工程与架构规范**（该怎么设计） |

> 具体命名（模块名/文件名/方法名）在本套文档里多为**示例、可自定**；约束的是**做法与结构**，不是具体名字。