27142804d6
新增关键动作时间线记录和展示功能，完善失误分析模块： 1. 添加 ReviewActionTimelineItem 记录结构，用于记录关键动作事件 2. 在 ReviewSummaryResponse 中增加 actionTimeline 字段 3. 扩展 ReviewMistakeItem 结构，新增关联动作、推荐方向、压力来源等字段 4. 实现动作时间线构建和失误关联动作查找逻辑 5. 前端增加动作时间线和详细失误信息的展示组件 6. 更新文档说明当前复盘协议已支持真实对局数据 这些改动使复盘系统能够展示更详细的对局过程分析和更精准的失误定位，帮助玩家更好地理解对局关键节点和改进方向。
344 lines
9.0 KiB
Markdown
344 lines
9.0 KiB
Markdown
# 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` 这套字段上的语义对齐，并逐步从结算摘要扩到过程回放。
|
|
|
|
当前前端已经能手动加载当前真实对局、当前视角的复盘摘要，并渲染关键动作时间线；关键失误也开始挂接到关联动作步骤、推荐方向标签和局面信号。
|
|
|
|
这一版关键失误协议还额外补了一层“压力来源细节”说明：
|
|
|
|
- `pressureSourceDetail`
|
|
- 用一段面向玩家可读的短文，把“哪家在施压、这股压力由什么公开动作或残局窗口形成、你这一步为什么正好撞上去”串起来
|
|
- 当前仍是启发式生成，不等同于完整牌谱推演或可见信息搜索
|
|
|
|
### 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` 完成的标准不是“页面完全重写”，而是：
|
|
|
|
- 正式对局页的职责边界已经明确
|
|
- 私有区、公共区、动作区层级已经固定
|
|
- 下一轮前端可以按文档和当前代码骨架继续拆，不必重新讨论页面结构
|
|
|
|
当前结论：已满足。
|