xzmaster/docs/H5_GAME_PAGE_ARCHITECTURE.md

H5 对局页信息架构与页面拆分方案

当前状态快照日期：2026-03-20

---

1. 文档目标

这份文档用于落实 S1-08，为 H5 原型页向正式页面演进提供可以直接执行的拆分输入。

它要解决的不是“最终视觉长什么样”，而是先把下面几件事固定下来：

• 页面边界怎么切
• 正式对局页内部区域怎么分
• 公共消息和私有消息分别落在哪个区
• 哪些状态应该留在页面容器，哪些应该沉到子组件
• 下一轮前端继续拆页时，如何避免再次把逻辑堆回 App.vue

这符合：

• KISS：先拆职责边界，不先追求完整视觉重写
• YAGNI：当前不引入路由级复杂壳层和状态库
• SOLID：页面容器、消息面板、动作面板、公共时间线分层明确
• DRY：共享类型与格式化函数抽离，避免多组件重复维护

---

2. 当前现状判断

当前 frontend/src/App.vue 已经承担了四类职责：

1. 房间流操作
2. 对局页状态与动作提交
3. WebSocket 订阅与消息清理
4. 消息卡片、结算卡片、时间线等展示

这说明它已经不再是“临时原型脚本”，而是一个事实上的页面容器。

当前如果继续在 App.vue 里叠加：

• 断线重连提示
• 教学开关
• 复盘入口
• 页面级切换
• 更多正式规则结算展示

后续维护成本会快速上升。

---

3. 正式页面拆分建议

3.1 页面层级

建议前端逐步演进为以下页面：

• HomePage
  • 负责产品入口、快速建房、邀请码输入、最近房间入口
• RoomPage
  • 负责建房后、开局前的房间管理与玩家准备
• GamePage
  • 负责正式对局中的牌桌、动作、教学、公共事件
• ReviewPage
  • 负责局后个人复盘、关键失误与建议回看

当前阶段不要求一次性引入完整路由，但组件组织和文档命名要按这个终态准备。

当前代码层已经落下对应的页面级容器命名：

• frontend/src/pages/RoomPageContainer.vue
• frontend/src/pages/GamePageContainer.vue
• frontend/src/pages/ReviewPageContainer.vue

其中 ReviewPageContainer 当前仍是占位实现，用于固定页面职责，不代表已经接入真实复盘数据。

当前还补了一条最小演示协议入口：

• 后端真实接口：GET /api/games/{gameId}/review?userId={userId}

它的目标不是替代真实局后数据，而是先把前后端在 ReviewSummaryResponse 这套字段上的语义对齐。

当前前端已经能在不接入正式路由的前提下，手动加载这条 demo 复盘数据并渲染 ReviewPageContainer。

3.2 当前这一轮的落地点

本轮先聚焦 GamePage。

原因：

• 房间流已经基本够用
• 当前复杂度主要集中在对局页
• 动作消息、教学消息、结算时间线都已经真实接入
• 正式血战计分规则后续迭代也主要会继续压在对局页

---

4. GamePage 信息分区

4.1 顶部概览区

职责：

• 显示对局阶段
• 显示当前视角
• 显示剩余牌墙
• 显示当前系统提示

说明：

• 顶部概览区只做“当前局势总览”
• 不承载具体动作按钮
• 不放长文教学解释，避免遮挡主桌面

4.2 自己手牌与当前动作区

职责：

• 展示自己的手牌与副露
• 承接定缺、主动回合动作
• 处理“点击手牌出牌”的高频交互
• 在手牌区局部高亮教学推荐牌

说明：

• 出牌仍保留“点击手牌直接触发”
• 杠、自摸胡等低频动作通过统一动作面板承接
• 这是为了保留 H5 的高频单手操作效率

4.3 响应动作区

职责：

• 响应窗口出现时展示 PENG / GANG / HU / PASS
• 清晰显示来源座位、目标牌、触发事件类型

说明：

• 该区域与“当前回合动作区”共用一个动作容器
• 但视觉上必须区分当前回合与响应窗口
• 当前项目已经实现统一动作消息结构，因此前端只需按 actionScope 切换视图

4.4 私有教学区

职责：

• 展示推荐动作
• 展示解释文案
• 展示候选牌、评分、原因标签

说明：

• 私有教学区必须与公共区域显著分离
• 教学候选列表属于私有信息，不得混入公共事件流
• 移动端下建议紧贴动作区，但与牌桌保持卡片边界

4.5 公共桌面区

职责：

• 展示其他座位的公开信息
• 展示弃牌、副露、积分、是否已胡

说明：

• 公共桌面区不显示其他玩家私有教学
• 这是消息边界在 UI 层的直接体现

4.6 公共事件与最近结算区

职责：

• 展示公共事件时间线
• 展示最近一次结算卡片
• 展示最近结算对应的分数变化

说明：

• 公共事件是调试和正式观感都需要保留的区域
• 但在正式页面中，它应当是“次主区”，不是最上方首屏主区

---

5. 组件拆分建议

5.1 页面容器组件

• GamePageContainer
  • 负责请求、WebSocket、页面级状态聚合
  • 负责“谁是当前视角用户”和“当前牌局状态”这两个页面主状态

当前阶段由 App.vue 暂代这个角色。

5.2 已建议先拆出的展示组件

本轮已经先按最小风险拆出三块：

• GameActionDock.vue
  • 只负责主动动作 / 响应动作展示与按钮提交
• GameMessageStack.vue
  • 只负责私有动作摘要卡与私有教学卡
• PublicEventTimeline.vue
  • 只负责最近结算、分数变化与公共事件时间线

这样做的目的不是“拆得越碎越好”，而是先把最容易继续膨胀的三个展示区从页面容器中拔出来。

5.3 下一轮建议继续拆的组件

• RoomControlPanel
  • 建房、入房、准备、开局入口
• SelfHandPanel
  • 手牌、副露、推荐牌高亮
• PublicSeatBoard
  • 其他玩家公开桌面
• ViewSwitchPanel
  • 多玩家视角切换

---

6. 状态归属建议

6.1 必须保留在页面容器的状态

• room
• game
• currentUserId
• publicEvents
• privateAction
• privateTeaching
• wsStatus
• busy
• error

原因：

• 它们同时被多个区域消费
• 其中 privateAction 与公共事件清理之间有联动
• currentUserId 变化会触发重拉状态与重连私有 WebSocket

6.2 可下沉为共享工具的内容

• 接口响应类型
• 私有/公共消息 DTO
• UI 标签映射
• 事件摘要格式化函数
• 结算详情解析函数

本轮已经落地为：

• frontend/src/types/game.ts
• frontend/src/utils/gameUi.ts

6.3 当前不建议引入的东西

• Pinia 等全局状态库
• 过早的页面级缓存层
• 复杂消息归档服务

原因：

• 当前页面仍是单条主链，复杂状态库会提升理解成本
• 现阶段优先保证规则联调和 H5 可操作性

---

7. 移动端布局建议

7.1 布局优先级

移动端从上到下建议为：

1. 顶部提示与对局摘要
2. 自己手牌区
3. 动作区
4. 私有教学区
5. 公共桌面区
6. 公共事件时间线

7.2 关键原因

• 手牌和动作区必须靠前，保证高频操作路径最短
• 私有教学紧跟动作区，减少视线切换
• 公共事件时间线放在靠后位置，避免压缩手牌点击区域

7.3 H5 交互要求回落

• 关键按钮保持大点击热区
• 不依赖 hover
• 响应窗口出现时动作按钮必须明显聚焦
• 私有教学不能遮住手牌

---

8. 本轮已经落地的最小结构调整

为降低后续继续拆页的成本，本轮已经完成以下基础整理：

• 抽离共享类型文件，减少组件间类型重复
• 抽离 UI 格式化工具，减少多处重复的事件/结算渲染逻辑
• 抽离动作面板组件
• 抽离私有消息栈组件
• 抽离公共事件时间线组件

这一步仍然保持：

• App.vue 作为页面容器
• 行为逻辑不变
• WebSocket 订阅逻辑不变
• 动作提交链路不变

---

9. 下一轮前端任务建议

建议按以下顺序继续：

1. 把 App.vue 演进为 GamePageContainer
2. 把房间流区域抽成 RoomPage 或 RoomControlPanel
3. 把手牌区和公共桌面区拆成独立组件
4. 再决定是否引入路由和页面级导航

如果下一轮要优先做体验而不是结构，建议优先加：

• 教学开关入口
• WebSocket 断线提示
• 对局结束后的复盘入口占位

---

10. 验收结论

S1-08 完成的标准不是“页面完全重写”，而是：

• 正式对局页的职责边界已经明确
• 私有区、公共区、动作区层级已经固定
• 下一轮前端可以按文档和当前代码骨架继续拆，不必重新讨论页面结构

当前结论：已满足。