feat(复盘): 实现关键动作时间线并增强失误分析

新增关键动作时间线记录和展示功能,完善失误分析模块:
1. 添加 ReviewActionTimelineItem 记录结构,用于记录关键动作事件
2. 在 ReviewSummaryResponse 中增加 actionTimeline 字段
3. 扩展 ReviewMistakeItem 结构,新增关联动作、推荐方向、压力来源等字段
4. 实现动作时间线构建和失误关联动作查找逻辑
5. 前端增加动作时间线和详细失误信息的展示组件
6. 更新文档说明当前复盘协议已支持真实对局数据

这些改动使复盘系统能够展示更详细的对局过程分析和更精准的失误定位,帮助玩家更好地理解对局关键节点和改进方向。
This commit is contained in:
hujun
2026-03-20 17:24:41 +08:00
parent faf87fe3d6
commit 27142804d6
9 changed files with 889 additions and 24 deletions

View File

@@ -1,16 +1,25 @@
# 局后复盘服务 V12026-03-20
- 已移除 demo 复盘链路:`DemoGameController` 不再暴露 `GET /api/demo/review``DemoGameService` 也已移除 demo review 生成逻辑。
- 新增真实复盘接口:`GET /api/games/{gameId}/review?userId={userId}`
- `ReviewController` 负责暴露接口,`ReviewService` 负责基于真实 `GameSession``settlementHistory` 生成 `ReviewSummaryResponse`
- `GameSessionService` 新增只读查询口 `getSessionForReview(String gameId)`,当前仅供复盘服务读取内存态会话;未引入新持久化或快照表。
- 当前复盘算法范围KISS/YAGNI 版本)
- 个人总览:读取当前座位最终分数、结果标签、总结文案。
- 当前真实复盘接口:`GET /api/games/{gameId}/review?userId={userId}`
- `ReviewController` 负责暴露接口,`ReviewService` 负责基于真实 `GameSession``events``settlementHistory` 生成 `ReviewSummaryResponse`
- `GameSessionService` 提供只读查询口 `getSessionForReview(String gameId)`,当前仅供复盘服务读取内存态会话;未引入新持久化或快照表。
- 当前复盘协议内容
- 个人总览:最终分数、结果标签、总结文案。
- 关键动作时间线:`actionTimeline`,从真实 `GameEvent` 中提炼个人相关关键节点与重要桌面节点,当前包含开局、阶段切换、定缺、个人摸打、响应窗口、个人响应动作、与本人相关结算等。
- 关键结算:从 `settlementHistory` 中筛出与该座位直接相关的结算,生成标题、摘要、分值和番型/结算标签。
- 关键失误:基于真实负向结算生成启发式问题项,当前覆盖点炮、自摸失分、抢杠胡、退税、查叫、明杠/杠类被动付分。
- 关键失误:基于真实负向结算生成启发式问题项,并补齐四层信息:
- 关联动作:`relatedStepNo``relatedEventType``relatedActionTitle`
- 推荐方向:`recommendedDirectionType``recommendedDirectionLabel``recommendedAction`
- 局面信号:`contextSignals`,当前从公开事件历史提炼触发牌、他家副露次数、牌墙余量、是否直接触发后续失分、是否已接近流局、是否处于补杠风险窗口等。
- 压力来源解释:`pressureSourceType``pressureSourceLabel``pressureSourceDetail``pressureSummary`,其中 `pressureSourceDetail` 会把“谁在施压、由什么公开动作或残局窗口形成、你这一步为什么撞上去”串成一段玩家可读说明。
- 训练方向:基于负向结算类型和是否有正向胡牌样本,生成风险控制、成叫效率、杠牌时机、基础番型等训练建议。
- 当前限制:
- 仍是内存态复盘,服务重启后对局与复盘数据会丢失。
- 还没有逐手牌谱回放、动作级失误定位、个人可见信息回放时间线
- `mistakeInsights` 仍是启发式生成,不是严格牌效/安牌分析
- 前端已改为手动加载当前真实对局/当前视角复盘;切换视角或切换对局时会清空旧复盘,避免显示过期摘要。
- 动作时间线是“关键动作摘要”,还不是完整逐手牌谱播放器
- 失误解释仍是启发式,不是严格牌效/安牌搜索;也没有真正的逐步可见信息快照
- 前端状态:
- 复盘页已能手动加载当前真实对局、当前视角的复盘摘要。
- 复盘页已展示:总览、关键动作回放、关键结算、关键失误、训练方向。
- 关键失误卡片当前已展示:关联动作、建议方向、压力来源标签、压力来源细节、压力摘要、局面信号。
- 切换视角或切换对局时会清空旧复盘,避免显示过期摘要。
- 已验证:`cd backend && mvn test` 通过;`cd frontend && npm run build` 通过。