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

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

---

## 这套文档解决什么

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

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

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

---

## 阅读导航

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

---

## 一页纸总则

**七大总则与适用边界已独立成篇：[一页纸总则.md](./一页纸总则.md)。**

该文件由 `CLAUDE.md` 通过 `@import` 常驻每次会话上下文，是总则的权威源；本 README 只负责导航，不重复抄写总则（避免两处不同步）。总则的展开见 [01-架构总则与分层.md](./01-架构总则与分层.md)。

---

## 与既有文档的关系

| 文档 | 定位 |
|------|------|
| 各端 `development-guide/` | 平台接入 + 工程红线（**能跑、合规**） |
| **本套 `engineering/`** | **平台无关的通用工程与架构规范**（该怎么设计） |

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