初始化仓库：友乐/gameabc 房卡游戏平台脚手架（client + server + docs）
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,170 @@
|
||||
# 03 · 数据收发与通信协议
|
||||
|
||||
本篇是**日常手册**：数据包长什么样、收包要做哪些固定步骤、三种发包方式怎么选、为什么"主动推送"是唯一可靠的下发通道，以及本项目最重要的一条——**成败标志只认 `data.success`**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 数据包结构
|
||||
|
||||
所有前后端数据包统一四字段：
|
||||
|
||||
```js
|
||||
{
|
||||
app: "youle", // 应用名（游戏固定 "youle"）
|
||||
route: "<你的游戏>", // 路由名 = 模块 routename
|
||||
rpc: "playCard", // 方法名，决定调到 mod 的哪个函数 / 前端走哪个解析分支
|
||||
data: { /* 业务数据 */ }
|
||||
}
|
||||
```
|
||||
|
||||
- `app/route/rpc` 三字段驱动三层路由（见 01）。
|
||||
- `data` 里**必含平台参数**：`agentid`、`playerid`、`gameid`、`roomcode`、`seat` 等；数值参数收包时要 `parseInt`。
|
||||
- **一包多信息**：一个响应包应携带本次状态变更的完整信息（出了什么牌、轮到谁、各家剩余、倒计时、比分……），减少往返。
|
||||
|
||||
---
|
||||
|
||||
## 2. 收包处理的固定步骤
|
||||
|
||||
每个 RPC handler 开头都是同一套"安检流程"，**不可省略、不可简化**：
|
||||
|
||||
```js
|
||||
mod_<游戏>.playCard = function(pack) {
|
||||
// 1) 提取参数（数值 parseInt）
|
||||
var agentid = pack.data.agentid;
|
||||
var playerid = parseInt(pack.data.playerid);
|
||||
var gameid = pack.data.gameid;
|
||||
var roomcode = parseInt(pack.data.roomcode);
|
||||
var seat = parseInt(pack.data.seat);
|
||||
|
||||
// 2) 校验玩家与房间（必做）——失败静默 return
|
||||
var o_room = mod_<游戏>.import.check_player(
|
||||
agentid, gameid, roomcode, seat, playerid, pack.conmode, pack.fromid);
|
||||
if (!o_room) return;
|
||||
|
||||
// 3) 取桌对象与对局状态
|
||||
var o_desk = o_room.o_desk;
|
||||
if (!o_desk) return;
|
||||
|
||||
// 4) 业务校验（游戏阶段？轮到该座？操作合法？）——任一不过即 return
|
||||
// 5) 执行业务（委托权威模块）
|
||||
// 6) 构建并【主动推送】结果（见下文）
|
||||
};
|
||||
```
|
||||
|
||||
- **`check_player` 是强制安检**：它校验座位、连接、身份，返回 `o_room` 或 `null`。返回 `null` 一律直接 `return`。
|
||||
- **校验失败静默**：不要回 "你作弊了" 之类提示，直接 `return`，避免给作弊者反馈。
|
||||
- **调试记录**（若框架提供 `o_desk.debug.save_receivepack` 等）在关键节点调用，便于复盘。
|
||||
|
||||
---
|
||||
|
||||
## 3. 三种发包方式
|
||||
|
||||
| 方式 | 接口 | 用于 |
|
||||
|------|------|------|
|
||||
| 点对点 | `o_room.method.sendpack_toseat(msg, seat)` | 只发给某个座位（个人状态、定向数据） |
|
||||
| 广播其他人 | `o_room.method.sendpack_toother(msg, seat)` | 发给除 `seat` 外所有人（`seat=-1` 即全发） |
|
||||
| 差异化广播 | 逐座位组 `msg` 后各自 `sendpack_toseat` | 每个玩家看到的内容不同（如手牌只发本人） |
|
||||
|
||||
平台发包内部会**从 `seatlist[seat]` 上取 `conmode`/`fromid`** 填入包，再交给底层 `SendPack` 按 TCP/HTTP 下发——**这两个连接字段不需要你手工设置**，只要座位上有在线玩家即可。
|
||||
|
||||
### 差异化广播：棋牌最常用
|
||||
|
||||
牌类游戏里"同一动作、各家可见不同"，所以广播时为每个座位**深拷贝一份基础数据再定制**：
|
||||
|
||||
```js
|
||||
for (var seat = 0; seat < o_room.seatlist.length; seat++) {
|
||||
if (!o_room.seatlist[seat]) continue; // 空座跳过
|
||||
var msg = {
|
||||
app: "youle", route: "<游戏>", rpc: "playCard",
|
||||
data: deepCopy(baseData) // 公共信息
|
||||
};
|
||||
if (seat === actionSeat) {
|
||||
msg.data.handCards = hands[seat]; // 仅本人可见手牌
|
||||
} else {
|
||||
msg.data.handCards = []; // 他人看不到
|
||||
}
|
||||
o_room.method.sendpack_toseat(msg, seat);
|
||||
}
|
||||
```
|
||||
|
||||
> 敏感信息（手牌、暗牌、未公开的判定）**只发给该看到的人**，这是服务器权威的一部分。
|
||||
|
||||
---
|
||||
|
||||
## 4. 主动推送是唯一可靠的下发通道
|
||||
|
||||
**前端收包的唯一通道是服务端主动推送**（`sendpack_toseat / toother` → 底层 `SendPack`）。
|
||||
|
||||
而 RPC 方法的 **`return` 值不可靠下发前端**：框架虽会对 `DoPack` 的返回值做一次回发，但它只回当前请求连接、不按座位定向，浏览器/友乐链路下不能当作状态推送通道（机制见 01 §4）。
|
||||
|
||||
**推论**：凡需要让前端看到的结果（包括操作的成功/失败），都必须放进**主动推送的 `data`** 里。
|
||||
|
||||
---
|
||||
|
||||
## 5. 成败标志协议（本项目最重要的一条）
|
||||
|
||||
> 这条覆盖并修正了早期文档里"用 HTTP 风格 `status` 码判成败"的写法。**以本协议为准。**
|
||||
|
||||
### 规则
|
||||
|
||||
1. **成败唯一权威字段是 `data.success`（boolean）**。前端一律 `if (!data.success)` 判断操作成败。
|
||||
2. **禁止用 `data.status`（如 `status === 200`）或 `data.code` 判成败**。`status`/`code` 只能作展示/日志用的细分信息，不参与成败裁定。
|
||||
3. **主动推送必须自带 `success`**：因为 `return` 不下发前端，凡有成败语义的**推送包**，其 `data` 必须显式带 `success: true/false`，不能只放 `status`。
|
||||
4. **禁止双轨/兼容兜底**：前端不得写 `status !== 200 && !success` 之类的 `status` 兜底；新增/改动的推送一律补齐 `success`，前端一律只认 `success`。
|
||||
|
||||
### 正反例
|
||||
|
||||
```js
|
||||
// ❌ 错误：推送只带 status，前端读 data.success 恒 undefined → 误判失败
|
||||
o_room.method.sendpack_toseat({
|
||||
app:"youle", route:"<游戏>", rpc:"setHostingState",
|
||||
data: { status: 200, hosting: true } // 少了 success
|
||||
}, seat);
|
||||
|
||||
// ✅ 正确：成败语义放 success，status 仅作细分
|
||||
o_room.method.sendpack_toseat({
|
||||
app:"youle", route:"<游戏>", rpc:"setHostingState",
|
||||
data: { success: true, status: 200, hosting: true }
|
||||
}, seat);
|
||||
```
|
||||
|
||||
```js
|
||||
// 前端：只认 success
|
||||
if (!data.success) { /* 失败处理 */ return; }
|
||||
// data.status / data.code 仅用于展示或日志细分
|
||||
```
|
||||
|
||||
> 典型事故：托管状态推送 `{ status: 200, ... }` 不带 `success`，前端读 `data.success` 恒为 `undefined`，于是"已进入托管却报失败"。根因就是违反了本协议第 3 条。
|
||||
|
||||
---
|
||||
|
||||
## 6. 前后端对接的固定接缝
|
||||
|
||||
下发结构变了，对应的前端解析接口必须同步检查（前端平台代码与受限接口文件不可随意改，见 04）：
|
||||
|
||||
| 场景 | 服务端产出 | 前端接收接口 |
|
||||
|------|------------|--------------|
|
||||
| 开战 | `export.makewar` 的返回包 | `Game_Modify.StartWar(makewar 返回值)` |
|
||||
| 重连/中途加入 | `export.get_deskinfo` 的返回 | `Game_Modify.Reconnect(get_deskinfo 返回值)` |
|
||||
| 对局操作 | RPC handler 的主动推送（按 `rpc` 区分） | 前端对应 `rpc` 的解析分支 |
|
||||
|
||||
**改服务端下发 = 同步核对前端解析**，否则前端按旧结构解析必然出错。
|
||||
|
||||
---
|
||||
|
||||
## 7. 服务端代替玩家操作时的透明性
|
||||
|
||||
服务端自动替玩家执行的操作（如 AI 托管出牌/碰杠胡），**必须复用真人操作的同一套数据包与广播链路**：产生的包结构、`rpc`、`data` 与真人操作**完全一致**，前端无需也禁止为它单开一套接收/解析分支。唯一区别只在触发源（前端请求 → 服务端决策），其后的数据组织、协议、广播路径不变。（详见 04 的对应红线。）
|
||||
|
||||
---
|
||||
|
||||
## 8. 小结
|
||||
|
||||
- 包结构恒为 `{app, route, rpc, data}`；收包先 `check_player`，失败静默 `return`。
|
||||
- 三种发包方式按"谁该看到什么"选；差异化广播逐座位定制，敏感信息只发本人。
|
||||
- **主动推送是唯一可靠下发通道**，`return` 不算。
|
||||
- **成败只认 `data.success`**，推送必自带 `success`，禁止 `status`/`code` 判成败与兼容兜底。
|
||||
- 改下发结构必同步核对前端 `StartWar`/`Reconnect`/对应 `rpc` 解析。
|
||||
|
||||
下一篇 [04-开发规范与红线](./04-开发规范与红线.md) 汇总所有必须遵守的工程纪律。
|
||||
</content>
|
||||
Reference in New Issue
Block a user