服务端 · 子游戏开发指导文档
本套文档是友乐游戏平台下「子游戏服务端」开发的通用指导与规范。 它讲清楚三件事：框架怎么运作、子游戏怎么接进去、开发时必须守哪些规矩。
文中以「麻将」一类房卡棋牌作举例，但所有结论都是框架通用的，不绑定任何具体玩法。 新开发者按本套文档即可理解运作流程、动手接入并写出符合规范的子游戏。
这套文档写给谁
- 新接手子游戏服务端的开发者：先读完 01、02 建立全局认知，再按 03、04 动手。
- 正在开发/维护某个子游戏的开发者：03、04 是日常红线，改任何东西前回查。
- 做代码审查的人：04 是审查清单的来源。
阅读顺序
| 篇 | 文档 | 解决什么问题 |
|---|---|---|
| 00 | 本文 README | 这套文档是什么、怎么读、红线速查 |
| 01 | 01-服务端环境与框架基础.md | 平台与子游戏的关系、核心对象模型、三层路由、房间生命周期 |
| 02 | 02-子游戏接入与开发流程.md | 三文件架构、export/import 接口、makewar/重连、一次操作的完整数据流 |
| 03 | 03-数据收发与通信协议.md | 包结构、收发包方式、主动推送、成败标志协议、前后端对接点 |
| 04 | 04-开发规范与红线.md | 可编辑范围、ES5/require、数据权威、模块职责、房间隔离、测试纪律 |
建议第一次从 01 顺序读到 04；之后把 03/04 当手册随用随查。
一页纸：核心运作模型
客户端数据包 { app, route, rpc, data }
│
▼
packet_face.ReceivePack 按 pack.app 找到「应用」
│
▼
app.ReceivePack 按 pack.route 找到「模块」(子游戏)
│
▼
mod.DoPack 按 pack.rpc 调到「方法」 mod[rpc](pack)
│
▼
子游戏 RPC handler 校验玩家 → 取对局状态 → 执行业务 → 主动推送
│
▼
o_room.method.sendpack_toseat 按座位取连接信息(conmode/fromid) → 下发客户端
- 平台框架负责：网络收发、应用/模块/房间/玩家对象、路由、房卡、战绩、房间生命周期。
- 子游戏负责：玩法规则、对局状态、每个操作的处理与广播。两者通过 export / import 两组接口对接。
红线速查（详见 04）
以下每一条都有过真实事故或返工，改代码前先对照。
- 可编辑范围：服务端只能改
server/games2/<你的游戏>/，server/其余皆平台代码，禁改。 - 双运行时：代码同时跑在 Node 与浏览器/友乐平台。必须严格 ES5；
require只能写在文件开头if (typeof require !== 'undefined') {}守卫块内，禁止函数体内/中途 require。 - 成败标志唯一是
data.success：前端只认if (!data.success)；主动推送的data必须自带success（mod 的return值不可靠下发前端）；禁止用status/code判成败、禁止status兼容兜底。 - 数据权威：同一业务数据只有一个权威来源，下游只读不重算；权威字段缺失要显式报错/返回 null，禁止
|| 0、|| []、|| ''兜底掩盖。 - 模块职责边界：一个职能只在一个模块实现，其他模块调用而非重造。
- 房间隔离：一切随对局变化的状态都挂
o_room.o_desk.data.*；禁止模块级单例/全局变量存对局态；缓存/定时器/决策表不得只用seat作 key，必须房间 + seat；结束/解散/开新局时按房间清理全部定时器与残留状态。 - 服务端自动操作复用真人链路：服务端代替玩家做的操作（如 AI 托管）必须复用「真人操作」的同一套处理入口与广播链路，对前端透明，不为它单开一套下发分支。
- 服务器权威：房卡、胜负、积分、状态等关键数据与操作一律以服务器为准，前端数据仅供显示。
- 测试纪律：测试失败先用证据裁定「业务缺陷 vs 测试脚本缺陷」，禁止 skip/软化断言/吞异常掩盖；正式代码不得为兼容测试而加逻辑。
与既有文档的关系
- 平台级、面向「所有子游戏」的总纲在
docs/important/server/（友乐框架收发包规范、子游戏开发要求）。 - 本套文档是其落地版：结合本仓库真实代码，给出可直接照做的接入步骤与红线，并对其中已被本项目实践修正的部分（如成败标志由
status收敛为success）以本套为准。 - 各子游戏内部的架构细节（模块划分、算法）仍以各自
games2/<游戏>/docs/为准。