整理文档并接入 H5 体验测试链路

doc/result-scene-proposal.md

@@ -0,0 +1,293 @@
+# 游戏结算层方案
+
+## 1. 目标
+
+为游戏结束后的结果展示建立独立结算层，不把结算逻辑散落在：
+
+- 规则层
+- HUD
+- 顶部提示
+- 页面临时弹窗
+
+目标是：
+
+- 统一承接结束态
+- 展示成绩与摘要信息
+- 支撑不同玩法的结算差异
+- 为后续文创奖励、奖章、分享做扩展位
+
+一句话：
+
+**把“比赛结束后显示点什么”提升为正式的结果场景能力。**
+
+---
+
+## 2. 当前现状
+
+当前项目已经有：
+
+- `session_finished`
+- `gameSessionStatus = finished`
+- 基础成绩、里程、时长、心率等 telemetry
+- 游戏信息面板可读取当前状态快照
+
+但还没有正式的：
+
+- `ResultScene`
+- `SummaryModel`
+- 结束后专属页面承载
+
+---
+
+## 3. 设计原则
+
+### 3.1 结算不应只是提示条
+
+结束不是一个瞬时反馈，而是一次阶段切换。
+
+所以它需要独立层，而不是只弹一句：
+
+- 已完成
+- 已结束
+
+### 3.2 结算要与玩法解耦
+
+顺序赛、积分赛、后续幽灵赛、金币赛，结算内容不同。
+
+所以应该有：
+
+- 通用结算结构
+- 玩法补充区块
+
+### 3.3 结算要可扩
+
+后续可能加入：
+
+- 奖章
+- 排名
+- 收藏卡
+- 文创解锁
+- 分享图
+
+所以一开始就要留结构。
+
+---
+
+## 4. 建议的新层级
+
+建议增加：
+
+- `ResultScene`
+
+概念上与这些层并列：
+
+- `MapPresentation`
+- `HUD`
+- `Feedback`
+- `ContentExperienceLayer`
+
+职责：
+
+- 承接结束态
+- 持有结算模型
+- 控制显示与关闭
+- 为玩法结果提供统一展示结构
+
+---
+
+## 5. 建议的数据模型
+
+### 5.1 SummaryModel
+
+```ts
+interface ResultSummaryModel {
+  title: string
+  subtitle: string
+  mode: string
+  finished: boolean
+  durationMs: number
+  distanceMeters: number
+  averageSpeedKmh: number | null
+  calories: number | null
+  averageHeartRateBpm: number | null
+  completedCount: number
+  skippedCount: number
+  totalCount: number
+  score: number | null
+  extraRows: Array<{ label: string; value: string }>
+}
+```
+
+### 5.2 ResultSceneState
+
+```ts
+interface ResultSceneState {
+  visible: boolean
+  summary: ResultSummaryModel | null
+}
+```
+
+---
+
+## 6. 第一阶段应展示什么
+
+建议先做一版“基础结算页”，不要一上来做复杂演出。
+
+### 通用区域
+
+- 赛事名称
+- 玩法名称
+- 完成状态
+- 总用时
+- 总里程
+- 平均速度
+- 卡路里
+- 平均心率
+
+### 玩法区域
+
+顺序赛：
+
+- 完成控制点数量
+- 跳过点数量
+- 总控制点数量
+
+积分赛：
+
+- 总得分
+- 已完成点数
+- 未完成点数
+
+### 操作区
+
+- 返回地图
+- 关闭
+- 后续再加重开 / 分享
+
+---
+
+## 7. 配置建议
+
+建议在配置中预留：
+
+```json
+{
+  "game": {
+    "result": {
+      "enabled": true,
+      "showTelemetry": true,
+      "showCollectedContent": true,
+      "showAwards": false,
+      "template": "default"
+    }
+  }
+}
+```
+
+这意味着：
+
+- 结算是否启用
+- 展示哪些区块
+- 用哪个模板
+
+都可配置。
+
+---
+
+## 8. 与当前架构的关系
+
+### 规则层
+
+负责：
+
+- 产出 `session_finished`
+
+### Telemetry
+
+负责：
+
+- 提供里程、速度、心率、卡路里等数据
+
+### MapEngine
+
+负责：
+
+- 在结束时汇总通用结算模型
+- 把结果快照送到页面层
+
+### 页面层
+
+负责：
+
+- 渲染结算页
+
+---
+
+## 9. 第一阶段最小实施范围
+
+建议第一阶段只做：
+
+1. `session_finished -> ResultScene`
+2. 基础 summary 展示
+3. 顺序赛 / 积分赛的简单差异化字段
+4. 手动关闭 / 返回地图
+
+先不要一上来做：
+
+- 复杂章节动画
+- 排名
+- 分享图生成
+- 复杂奖章系统
+
+---
+
+## 10. 后续扩展方向
+
+这层建好后，可以逐步加：
+
+- 文创奖励
+- 奖章 / 成就
+- 排名
+- 解锁内容
+- 分享卡
+- 二次引导
+
+---
+
+## 11. 推荐实施顺序
+
+1. 定义 `ResultSummaryModel`
+2. 在 `MapEngine` 汇总结束快照
+3. 页面层增加结果面板
+4. 顺序赛 / 积分赛各补一组玩法字段
+5. 再考虑动画、奖励和品牌内容
+
+---
+
+## 12. 与文创体验层的配合
+
+后续建议：
+
+- 文创体验层
+  - 承接“游戏中途”的体验
+- 结算层
+  - 承接“游戏结束后”的体验
+
+二者不要混。
+
+如果后续结算后要解锁文创卡片，可以由：
+
+- `ResultScene`
+  - 显示结算
+- 结算完成后
+  - 再触发内容奖励卡
+
+---
+
+## 13. 结论
+
+当前最合适的方向不是继续在结束时零散堆文案，而是：
+
+**正式增加一层 `ResultScene`，承接顺序赛、积分赛以及未来更多玩法的统一结算体验。**
+
+第一阶段先做基础 summary，后续再逐步接入文创奖励、奖章、排名和过场动画。