# 游戏结算层方案
> 文档版本：v1.0
> 最后更新：2026-04-02 08:28:05


## 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，后续再逐步接入文创奖励、奖章、排名和过场动画。



