3.1 KiB
3.1 KiB
服务端 · 子游戏开发指导文档
本套文档是友乐游戏平台下「子游戏服务端」开发的通用指导与规范。 它讲清楚三件事：框架怎么运作、子游戏怎么接进去、开发时必须守哪些规矩。
文中以「麻将」一类房卡棋牌作举例，但所有结论都是框架通用的，不绑定任何具体玩法。 新开发者按本套文档即可理解运作流程、动手接入并写出符合规范的子游戏。
这套文档写给谁
- 新接手子游戏服务端的开发者：先读完 01、02 建立全局认知，再按 03、04 动手。
- 正在开发/维护某个子游戏的开发者：03、04 是日常红线，改任何东西前回查。
- 做代码审查的人：04 是审查清单的来源。
阅读顺序
| 篇 | 文档 | 解决什么问题 |
|---|---|---|
| 00 | 本文 README | 这套文档是什么、怎么读 |
| — | 红线速查.md | 一页纸运作模型 + 命名约定 + 红线清单（由 CLAUDE.md 常驻加载，改代码前先对照） |
| 01 | 01-服务端环境与框架基础.md | 平台与子游戏的关系、核心对象模型、三层路由、房间生命周期 |
| 02 | 02-子游戏接入与开发流程.md | 三文件架构、export/import 接口、makewar/重连、一次操作的完整数据流 |
| 03 | 03-数据收发与通信协议.md | 包结构、收发包方式、下发面发全 / 按可见性裁剪 / 状态机唯一在服务端、主动推送、成败标志协议、前后端对接点 |
| 04 | 04-开发规范与红线.md | 可编辑范围、ES5/require、数据权威（含前端不是数据源）、模块职责、房间隔离、请求合法性验证、测试纪律 |
建议第一次从 01 顺序读到 04；之后把 03/04 当手册随用随查。
一页纸与红线
运作模型、命名约定与红线清单已独立成篇：红线速查.md。
该文件由 CLAUDE.md 通过 @import 常驻每次会话上下文，是红线的权威源；本 README 只负责导航，不重复抄写红线（避免两处不同步）。红线的完整细节见 04-开发规范与红线.md。
与既有文档的关系
- 本套文档是平台级收发包/子游戏开发规范的落地版：结合本仓库真实代码，给出可直接照做的接入步骤与红线，并对其中已被本项目实践修正的部分（如成败标志由
status收敛为success）以本套为准。 - 各子游戏内部的架构细节（模块划分、算法）仍以各自
<游戏容器目录>/<游戏>/docs/为准。 - 平台无关的通用工程与架构规范（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 工程与架构通则：本套讲"平台怎么接、红线是什么"，工程通则讲"该怎么设计、怎么长久演进"，互补阅读。