二七王：精灵常量再优化为 View → group 容器 → 精灵

group 与其名下精灵合并为 { id: 群组常量, 精灵键: id, ... }，
所属关系由结构表达而非注释；拿到 group 对象即可 showGroup 并遍历其精灵。

SpriteIndex 随之支持 groupIdOf：精灵与群组 ID 被结构绑定，
显隐走群组时可机械查出。校验增至 5 处显式失败（重复键、精灵值非数字、
View 下混入标量键、group 缺 id、查不到的键）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-08-26-二七王前端A-地基与逻辑层-design.md

@@ -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`）：`Layer` / `Group` 扁平声明在 View 下（用到多个时写 `Layer1`/`Group2`…），精灵只写 id、所属关系在注释里。每个精灵注明类型 / 用途 / 资源键 / 帧说明 / 所属群组 |
+| `Sprites_*.js` | `EQW_Sprites` | 清单 §5.1–§5.8。**以 UI View 为组织单位**（一个 View 将来对应一个 `BaseComponent`），View 下是一个个 **group 容器**：`{ Layer: 图层, GroupName: { id: 群组, 精灵键: id, … } }`。用到多个图层时写 `Layer1`/`Layer2`。每个精灵注明类型 / 用途 / 资源键 / 帧说明 |
 | `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`、冲关牌） |
@@ -189,20 +189,40 @@ EQW_SeatMap.toSeat(displayKey, mySeat) // → 服务端座位号
 
 ### 5.5 `SpriteIndex`
 
-精灵常量以 UI View 为组织单位（`Layer`/`Group` 扁平声明在 View 下，精灵只写 id），而布局配置里 `attach.target` 写的是**键名**（清单 §6.1：「`target` 一律写键名而非数字 ID」）。故需一张扁平索引：
+精灵常量的组织是 **View → group 容器 → 精灵**：
 
 ```js
-EQW_SpriteIndex.build(spriteTree)      // 遍历 树 → View → 键 → { 键名: 精灵ID }
-EQW_SpriteIndex.idOf(key)              // 查 ID；查不到显式抛错，不返回 undefined
+EQW_Sprites.TopInfoView = {
+    Layer: EQW_Layers.TABLE_STATIC,              // 用到多个图层时写 Layer1 / Layer2…
+    TopInfo: {                                   // group 容器
+        id: EQW_Groups.TOP_INFO,
+        TOP_INFO_BG:   1001,
+        TOP_CALL_TEXT: 1003
+    }
+};
 ```
 
-**保留键约定**：View 内键名为 `Layer` / `Group` 或带数字后缀（`Layer1`、`Group2`…）的是 View 级声明，跳过不进索引；其余键一律是精灵 id。
+而布局配置里 `attach.target` 写的是**键名**（清单 §6.1：「`target` 一律写键名而非数字 ID」），故需把这棵树展平：
 
-**显式失败**三处（工程总则 §7）：
+```js
+EQW_SpriteIndex.build(spriteTree)         // → { 键名: 精灵ID }
+EQW_SpriteIndex.buildGroupMap(spriteTree) // → { 键名: 群组ID }
+EQW_SpriteIndex.init(spriteTree)          // 默认用 EQW_Sprites 建好两张索引
+EQW_SpriteIndex.idOf(key)                 // 查精灵 ID；查不到显式抛错
+EQW_SpriteIndex.groupIdOf(key)            // 查它所属的群组 ID；查不到显式抛错
+```
 
-- 键名拼错时 `idOf` 立即报错，而不是把 `undefined` 传给 `SpriteManager` 静默无效；
+`groupIdOf` 是这个结构带来的收益：group 容器把精灵与群组 ID 绑在一起，「某个精灵属于哪个群组」于是可以机械查出——显隐走群组时（前端红线：显隐由组件的 `showXxx`/`hideXxx` 控制）不必再手工对照。
+
+**结构约定**：View 内 `Layer`（含 `Layer1`/`Layer2`…）是 View 级声明、跳过；其余键的值必须是**对象**（group 容器）。group 容器内 `id` 是群组 ID、跳过；其余键一律是精灵 id。
+
+**显式失败**五处（工程总则 §7）：
+
+- `idOf` / `groupIdOf` 键名拼错时立即报错，而不是把 `undefined` 传给 `SpriteManager` 静默无效；
 - **重复键报错**而非后者覆盖前者——覆盖会让某个界面静默指向另一个界面的精灵。同名键在不同 View 下重复由清单 §5 的键名设计避免（`PLAY_SELF_*` / `PLAY_LEFT_*` / `PLAY_RIGHT_*`）；
-- **值非数字报错**——View 级声明与精灵条目在结构上同级、只靠键名区分，写错前缀（如 `Grup: 201`）会静默变成一个假精灵，故把「值不是数字」当作错误抓出来。
+- **精灵值非数字报错**；
+- **View 下混入标量键报错**（例如把群组 ID 误写成 View 级的 `Group: 201` 而没包进 group 容器）；
+- **group 容器缺 `id` 报错**。
 
 ---