二七王：S-4 拆分 bottomcards 字段名，S-5 术语同步收口
S-4（服务端改动）：底牌与埋牌底牌不再共用一个字段名。 - bottomcards = 底牌（发牌留桌 8 张）—— shangzhuang / ChooseMain / BuryCards，保持不变 - burycards = 埋牌底牌（庄家埋下 8 张）—— maipai（mod.js）、PushCards（class.export.js） - 结算 bottom.cards 未改名（分组名已表明是抠底相关），文档注明其语义 测试： - test_leak.js 的 CARD_FIELDS 白名单加入 burycards。这一步是必须的——不加的话 新字段会静默脱离下发面审计，闲家误收也发现不了。 - test_rpc.js 新增 11 条正反用例：庄家有 burycards 且为 8 张、庄家不再有 bottomcards（抓改名漏改）、闲家两个字段皆无、重连 PushCards 同上。 验证（不止「跑过了」）： - 改动前基线 16 个文件全绿；改动后仍全绿，新增后 rpc 从 89 → 100 checks。 - 反向验证一：把 mod.js 的 burycards 改回 bottomcards → test_rpc 新用例 FAIL， 且 test_leak 报出真实泄露（赋值改了而 delete 没改时，闲家会收到庄家埋的牌）。 - 反向验证二：删掉闲家侧的 delete msg.data.burycards → test_leak 立刻抓出 5 张越权牌，确认 burycards 确已纳入审计白名单。 两次验证后均已还原并复跑全绿。 S-5：术语同步收口。design.md / packet_protocol.md / 代码注释均已改用 「底牌 / 埋牌底牌」；compliance 三份历史核对记录有意不改（反映当时的 design 表述，下轮核对按新 design 重做）。 另：T-9 亮牌条文案暂定「x对 x主」（取 liangpai.zhupair 与 zhu，其余档位 先不渲染、协议不变）。至此 29 项待确认规格全部有结论。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
+48
-36
@@ -45,12 +45,12 @@
|
||||
|
||||
| 术语 | 指哪 8 张 | design.md 原称 | 当前协议字段 |
|
||||
| --- | --- | --- | --- |
|
||||
| **底牌** | 发牌时**没有发给玩家**、留在桌面的 8 张 | ~~暗牌~~ | `shangzhuang.bottomcards`、`ChooseMain`/`BuryCards.bottomcards` |
|
||||
| **埋牌底牌** | 庄家埋牌时从手里扣下的 8 张 | ~~底牌~~ | `maipai.bottomcards`、`PushCards.bottomcards`、结算 `bottom.cards` |
|
||||
| **底牌** | 发牌时**没有发给玩家**、留在桌面的 8 张 | ~~暗牌~~ | **`bottomcards`** |
|
||||
| **埋牌底牌** | 庄家埋牌时从手里扣下的 8 张 | ~~底牌~~ | **`burycards`**（结算包为 `bottom.cards`） |
|
||||
|
||||
其余术语（埋牌、扣底、甩牌、毙牌、垫牌、捡分、子、奖…）沿用 design.md §1 不变。注意「**扣底**」仍指 design §6.3 那条规则——闲家用主牌赢下最后一轮后翻开**埋牌底牌**计分；底栏那个 `扣底` 按钮是「查看埋牌底牌」的入口，两者同名但不同义。
|
||||
|
||||
> ⚠️ **design.md 与 packet_protocol.md 尚未同步此变更**（见 §7.5 **S-5**）。在同步前，读那两份文档时要做一次心算转换；协议里两批牌**共用 `bottomcards` 字段名**，需按所在包判断语义（拆分建议见 **S-4**）。
|
||||
> ✅ `design.md` 与 `packet_protocol.md` **已同步此变更**（S-5 完成），协议字段名也已拆分为 `bottomcards` / `burycards`（S-4 完成）。
|
||||
|
||||
---
|
||||
|
||||
@@ -555,7 +555,13 @@ EQW_RoomOptions = {
|
||||
| `qi` | 7 ≥ 6 | 如 `6 张 7` |
|
||||
| `er` | 2 ≥ 6 | 如 `6 张 2` |
|
||||
|
||||
多条同时满足时组合展示。参考图显示为 `主牌对子: 1对` —— 文案与上表不完全对应【待确认 T-9】。
|
||||
**文案（暂定）**：显示 **`x对 x主`** —— 即「对子数 + 主牌总数」，例如 `3对 12主`。
|
||||
|
||||
- 取 `liangpai.zhupair`（对子数）与 `liangpai.zhu`（主牌总数）。这两项同属「固定主牌 ≥10 张」那一档，要么都有、要么都没有。
|
||||
- 其余三档（`wang` / `qi` / `er`）与 `zhutuo`（拖拉机数）当前**不进文案**；服务端仍照常下发，前端先不渲染，后续要加时不必改协议。
|
||||
- 若 `liangpai` 里没有 `zhu` / `zhupair`（庄家未达到「固定主牌 ≥10 张」这一档），**整条亮牌条不显示**。
|
||||
|
||||
> 暂定文案，正式稿到位后只改这一处模板。
|
||||
|
||||
### 1.7 出牌对局 `chupai1` / `chupai2` / `chupai3` 【图：出牌.png / 出牌2.png】
|
||||
|
||||
@@ -878,14 +884,14 @@ y≈648–720 深色条。左侧头像/昵称/分数由平台渲染（§0.2）
|
||||
>
|
||||
> 改后底栏按钮**名实相符**：`底牌` 按钮看底牌、`扣底` 按钮看埋牌底牌，不再有命名倒挂。
|
||||
>
|
||||
> **但协议字段目前仍两批共用 `bottomcards`**，只靠「在哪个包」区分语义，仍是易错点：
|
||||
> **协议字段也已拆开**（S-4 已完成），前端按字段名取值即可，不必再按所在包判断语义：
|
||||
>
|
||||
> | 按钮 | 展示 | 当前协议字段 | 建议改名（S-4） |
|
||||
> | --- | --- | --- | --- |
|
||||
> | `底牌` | 底牌（发牌留桌 8 张） | `shangzhuang.bottomcards`（庄家恒有，闲家仅 70 分时有）、`ChooseMain`/`BuryCards.bottomcards`（仅庄家） | 保持 `bottomcards` |
|
||||
> | `扣底` | 埋牌底牌（庄家埋的 8 张） | `maipai.bottomcards`、`PushCards.bottomcards`（仅庄家）、结算 `bottom.cards` | 改为 **`burycards`** |
|
||||
> | 按钮 | 展示 | 协议字段 |
|
||||
> | --- | --- | --- |
|
||||
> | `底牌` | 底牌（发牌留桌 8 张） | **`bottomcards`** —— `shangzhuang`（庄家恒有，闲家仅 70 分时有）、`ChooseMain`/`BuryCards`（仅庄家） |
|
||||
> | `扣底` | 埋牌底牌（庄家埋的 8 张） | **`burycards`** —— `maipai`、`PushCards`（仅庄家）；结算包为 `bottom.cards` |
|
||||
>
|
||||
> **实现要求**：前端内部用 `bottomCards`（底牌）/ `buryCards`（埋牌底牌）两个变量名区分；在 S-4 落地前，取值时必须按**所在包**判断 `bottomcards` 的语义。已列入验收清单（§7.3）。
|
||||
> **实现要求**：前端内部变量仍建议用 `bottomCards` / `buryCards` 区分，与字段名一一对应。已列入验收清单（§7.3）。
|
||||
|
||||
- 精灵：群组 205，号段 1040–1069（5 个按钮 × 2 精灵 = 10）。
|
||||
|
||||
@@ -1555,8 +1561,9 @@ codes/config/
|
||||
|
||||
## 7. 待补充清单
|
||||
|
||||
> **状态汇总**（2026-08-25）：待确认规格 29 项**已答 27 项**，剩 T-9（亮牌条文案）与 T-20（音效，已明确后续补充）。
|
||||
> 新增 **§7.5 服务端待补项**——3 条需要改服务端才能实现的前端需求。
|
||||
> **状态汇总**（2026-08-25）：待确认规格 29 项**已全部有结论**（T-9 亮牌文案暂定 `x对 x主`；T-20 音效明确后续补充）。
|
||||
> **§7.5 服务端待补项**共 5 条：**S-4 / S-5 已完成**（字段拆分 + 三份文档术语统一），**S-3 已定论**（无需改服务端），
|
||||
> 剩 **S-1**（抓分倍数字段 `curmultiple`）与 **S-2**（下发应选中的牌 `mustcard`）待实现。
|
||||
|
||||
### 7.1 待出设计稿的界面（后续统一补充）
|
||||
|
||||
@@ -1582,7 +1589,7 @@ codes/config/
|
||||
|
||||
| 编号 | 问题 | 影响 |
|
||||
| --- | --- | --- |
|
||||
| **T-9** | 亮牌条文案 `主牌对子: 1对` 与 design §8.2 四类信息（主牌总数/对子数/拖拉机数、王数、7 数、2 数）的对应关系与组合展示格式 | 文案模板；`liangpai` 各字段怎么拼成一行 |
|
||||
| ~~T-9~~ | ~~亮牌条文案~~ | **已暂定**：显示 `x对 x主`（见 §1.6） |
|
||||
| **T-20** | **整套音效**：清单、是否需要语音包、是否分男女声、倒计时提示音从第几秒起 | §4 全节；**已明确「等待后续补充」** |
|
||||
|
||||
**已定论（27 项）**
|
||||
@@ -1644,7 +1651,7 @@ codes/config/
|
||||
| 10 | `EQW_Layout` 与 `Game_Modify.PLAYER_INFO_LAYOUT` 的头像框坐标一致 | §6.11 |
|
||||
| 11 | 丢弃 `this.data`、仅凭最近一次服务端快照重画，界面完全一致 | 前端 05 §6.2 |
|
||||
| 12 | 所有布局参数都在配置文件里，业务代码无裸值 | §6 |
|
||||
| 13 | **底牌 / 埋牌底牌未写反**：`底牌` 按钮显示底牌（发牌留桌）、`扣底` 按钮显示埋牌底牌；内部变量用 `bottomCards`/`buryCards` 区分；S-4 落地前按「所在包」判断 `bottomcards` 语义 | §2.6 |
|
||||
| 13 | **底牌 / 埋牌底牌未写反**：`底牌` 按钮读 `bottomcards`、`扣底` 按钮读 `burycards`；内部变量 `bottomCards`/`buryCards` 一一对应 | §2.6 |
|
||||
| 14 | 叫分按钮配色按**档位位置**取（非按子数），已叫过的档位置灰 | §1.3 |
|
||||
| 15 | 自己发的提示本地回显后，收到失败回包时能撤掉 | §1.7 |
|
||||
|
||||
@@ -1734,34 +1741,39 @@ codes/config/
|
||||
|
||||
**服务端无需改动**——现有下发面正好支持这条规则：闲家在非 70 分局本来就收不到数据，按钮不显示即可，不存在「拿到了但不渲染」的泄露风险（服务端红线：下发即泄露）。
|
||||
|
||||
#### S-4 · 拆分 `bottomcards` 字段名（新增）
|
||||
#### S-4 · 拆分 `bottomcards` 字段名 —— ✅ 已完成（2026-08-25）
|
||||
|
||||
**需求**：底牌与埋牌底牌是两批不同的牌，协议里却共用 `bottomcards`，只靠所在包区分语义——易错，需要拆开。
|
||||
两批牌原先共用 `bottomcards`、只靠所在包区分语义，现已拆分：
|
||||
|
||||
**建议改法**（与新术语对齐，`bottomcards` 留给字面意义相符的「底牌」）：
|
||||
| 字段名 | 含义 | 出现在 |
|
||||
| --- | --- | --- |
|
||||
| **`bottomcards`** | **底牌**（发牌留桌 8 张） | `shangzhuang`、`deskinfo.ChooseMain`、`deskinfo.BuryCards` |
|
||||
| **`burycards`** | **埋牌底牌**（庄家埋下 8 张） | `maipai`、`deskinfo.PushCards` |
|
||||
| `bottom.cards` | **埋牌底牌** | 结算包 `bottom` 分组（分组名已表明是抠底相关，未改名） |
|
||||
|
||||
| 包 / 分组 | 当前字段 | 实际含义 | 建议 |
|
||||
| --- | --- | --- | --- |
|
||||
| `shangzhuang` | `bottomcards` | **底牌**（发牌留桌 8 张） | 保持 `bottomcards` |
|
||||
| `deskinfo.ChooseMain` | `bottomcards` | **底牌** | 保持 |
|
||||
| `deskinfo.BuryCards` | `bottomcards` | **底牌** | 保持 |
|
||||
| `maipai` | `bottomcards` | **埋牌底牌**（庄家埋的 8 张） | 改为 **`burycards`** |
|
||||
| `deskinfo.PushCards` | `bottomcards` | **埋牌底牌** | 改为 **`burycards`** |
|
||||
| 结算 `bottom` 分组 | `bottom.cards` | **埋牌底牌** | 分组名可一并改为 `bury`，或保持 `bottom.cards` 但在文档注明 |
|
||||
**服务端改动**：`mod.js`（`maipai` 组包）、`class.export.js`（`deskinfo.PushCards`），另同步了两处的注释术语。
|
||||
**测试**：`test/test_leak.js` 的 `CARD_FIELDS` 白名单加入 `burycards`（否则新字段会静默脱离下发面审计）；`test/test_rpc.js` 新增 11 条正反用例锁死拆分结果。
|
||||
**协议文档**：`packet_protocol.md` §0.0 与相关字段表已更新。
|
||||
|
||||
**影响面**：`packet_protocol.md`、服务端 `mod.js` / `class.paiju.js` / `class.desk.js` 的组包处，以及尚未开工的前端。**前端未开工，现在改代价最小。**
|
||||
**前端取值**：直接按字段名区分即可，不再需要「按所在包判断语义」：
|
||||
|
||||
#### S-5 · 同步 design.md 与 packet_protocol.md 的术语（新增）
|
||||
```js
|
||||
// 底牌（发牌留桌 8 张）——底栏「底牌」按钮
|
||||
data.bottomcards // shangzhuang / ChooseMain / BuryCards
|
||||
// 埋牌底牌（庄家埋下 8 张）——底栏「扣底」按钮
|
||||
data.burycards // maipai / PushCards
|
||||
data.bottom.cards // 结算包
|
||||
```
|
||||
|
||||
术语变更（暗牌→**底牌**、底牌→**埋牌底牌**）目前**只在本文生效**。`design.md` 是玩法**唯一权威源**，`packet_protocol.md` 是协议权威源，两者仍用旧术语——**三份文档术语打架会直接违反 SSOT**。
|
||||
#### S-5 · 同步 design.md 与 packet_protocol.md 的术语 —— ✅ 已完成（2026-08-25）
|
||||
|
||||
需要同步修订的位置（初步）：
|
||||
术语变更（暗牌→**底牌**、底牌→**埋牌底牌**）已在各处生效：
|
||||
|
||||
| 文档 | 位置 |
|
||||
| 文档 / 代码 | 状态 |
|
||||
| --- | --- |
|
||||
| `design.md` | §1 术语约定表（「暗牌」「底牌」「埋牌」「扣底」四条）；§4 开局与坐庄流程 3/5 步；§6.3 扣底；§7.1 70 分说明；§8 算奖快照；§9 查牌；§12.1 流程 4/6/8 步；§12.3 阶段速览 |
|
||||
| `packet_protocol.md` | `shangzhuang` / `maipai` / `deskinfo` 各分组的 `bottomcards` 说明；结算 `bottom` 分组；与 S-4 的字段改名一并做 |
|
||||
| 服务端代码 | 注释与变量名（非必须，但建议一并对齐） |
|
||||
|
||||
> **本文已先行采用新术语**，并在此显式记录差异，避免读者误以为 design.md 也已改。**建议尽快同步**，否则「底牌」一词在两份权威文档里指两批不同的牌，是最危险的那类不一致。
|
||||
|
||||
| `docs_dev/二七王-UI资源与精灵清单.md`（本文） | ✅ 全文新术语 |
|
||||
| `server/games/erqiwang/docs/design/design.md` | ✅ 全文 38 处替换；术语表后补「术语变更记录」说明改名缘由 |
|
||||
| `server/games/erqiwang/docs/protocol/packet_protocol.md` | ✅ 新增 §0.0 术语小节；字段说明同步；字段名随 S-4 拆分 |
|
||||
| `mod.js` / `class.export.js` / `test/test_leak.js` 注释 | ✅ 随 S-4 一并更新 |
|
||||
| `docs/compliance/*.md`（3 份，24 处） | ⬜ **有意不改**——这三份是历次核对的**历史记录**，反映当时的 design 表述；下轮核对按新 design 重做即可，不追溯修改 |
|
||||
| `test/*.js` 其余注释（约 14 处） | ⬜ 仅注释、不影响行为，后续顺手清理 |
|
||||
|
||||
Reference in New Issue
Block a user