二七王：确立「一个 View 恰好一个图层」不变式

原本允许 Layer1/Layer2 声明多图层，但「哪个 group 属于哪个图层」只能靠注释隐含、无法机械判定。改为跨图层的界面拆成两个 View，各带自己的 Layer—— 一个 View 将来对应一个 BaseComponent 组件，本就该分开。 SpriteIndex 加校验守住该不变式：View 缺 Layer、或写成 Layer1/Layer2 均报错。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-26 21:01:04 +08:00
parent 488f36b545
commit 69cb04ecfa
2 changed files with 25 additions and 16 deletions
@@ -104,7 +104,7 @@ client/tests/
 | `Groups.js` | `EQW_Groups` | 清单 §0.3 群组表 201–250 |
 | `ImageResources.js` | `EQW_Images` | 清单 §3 图片资源总表，**每条按 ImageResources.template 的要求注明用途 / 帧数 / 每帧含义 / 尺寸** |
 | `SoundResources.js` | `EQW_Sounds` | 清单 §4——**整节 T-20 未定**，本阶段只建文件骨架与说明注释，不臆造条目（见 §11） |
-| `Sprites_*.js` | `EQW_Sprites` | 清单 §5.1–§5.8。**以 UI View 为组织单位**（一个 View 将来对应一个 `BaseComponent`），View 下是一个个 **group 容器**：`{ Layer: 图层, GroupName: { id: 群组, 精灵键: id, … } }`。用到多个图层时写 `Layer1`/`Layer2`。每个精灵注明类型 / 用途 / 资源键 / 帧说明 |
+| `Sprites_*.js` | `EQW_Sprites` | 清单 §5.1–§5.8。**以 UI View 为组织单位**（一个 View 将来对应一个 `BaseComponent`），View 下是一个个 **group 容器**：`{ Layer: 图层, GroupName: { id: 群组, 精灵键: id, … } }`。一个 View 恰好一个图层，跨图层的界面拆成两个 View。每个精灵注明类型 / 用途 / 资源键 / 帧说明 |
 | `LayoutConstants.js` | `EQW_Layout` | 清单 §6.3 `textStyle` 预设、§6.4 `CARD_SIZE` 三档、座位键常量 `SELF/LEFT/RIGHT` |
 | `Layout_Table.js` | `EQW_Layout` | 清单 §6.5 常驻区 + §6.6 玩家位（含气泡朝向 `arrowRight`） |
 | `Layout_Cards.js` | `EQW_Layout` | 清单 §6.7 牌区（手牌单排/双排、底牌、埋牌底牌、已出牌 `bySeat`、冲关牌） |
@@ -193,7 +193,7 @@ EQW_SeatMap.toSeat(displayKey, mySeat) // → 服务端座位号

 ```js
 EQW_Sprites.TopInfoView = {
-    Layer: EQW_Layers.TABLE_STATIC,              // 用到多个图层时写 Layer1 / Layer2…
+    Layer: EQW_Layers.TABLE_STATIC,              // 一个 View 恰好一个图层
    TopInfo: {                                   // group 容器
        id: EQW_Groups.TOP_INFO,
        TOP_INFO_BG:   1001,
@@ -214,7 +214,7 @@ EQW_SpriteIndex.groupIdOf(key)            // 查它所属的群组 ID；查不

 `groupIdOf` 是这个结构带来的收益：group 容器把精灵与群组 ID 绑在一起，「某个精灵属于哪个群组」于是可以机械查出——显隐走群组时（前端红线：显隐由组件的 `showXxx`/`hideXxx` 控制）不必再手工对照。

-**结构约定**：View 内 `Layer`（含 `Layer1`/`Layer2`…）是 View 级声明、跳过；其余键的值必须是**对象**（group 容器）。group 容器内 `id` 是群组 ID、跳过；其余键一律是精灵 id。
+**结构约定**：View 内 `Layer` 是 View 级声明、跳过；**一个 View 恰好一个图层**——跨图层的界面拆成两个 View（一个 View 将来对应一个 `BaseComponent`，把两个图层塞进一个 View 会让「哪个 group 属于哪个图层」只能靠注释隐含）。其余键的值必须是**对象**（group 容器）。group 容器内 `id` 是群组 ID、跳过；其余键一律是精灵 id。

 **显式失败**五处（工程总则 §7）：

@@ -222,7 +222,8 @@ EQW_SpriteIndex.groupIdOf(key)            // 查它所属的群组 ID；查不
 - **重复键报错**而非后者覆盖前者——覆盖会让某个界面静默指向另一个界面的精灵。同名键在不同 View 下重复由清单 §5 的键名设计避免（`PLAY_SELF_*` / `PLAY_LEFT_*` / `PLAY_RIGHT_*`）；
 - **精灵值非数字报错**；
 - **View 下混入标量键报错**（例如把群组 ID 误写成 View 级的 `Group: 201` 而没包进 group 容器）；
- **group 容器缺 `id` 报错**。
+- **group 容器缺 `id` 报错**；
+- **View 缺 `Layer`（或写成 `Layer1`/`Layer2` 的多图层形式）报错**。

 ---