# H5 体验接入方案

本文档用于定义当前项目中 **原生小程序 + H5 定制内容** 的混合接入方案。

目标：

- 保留原生地图与实时游戏主流程
- 把高频变化、强定制的内容页交给 H5
- 保证 H5 失败时，原生仍可完整兜底
- 为后续客户定制、品牌包装、互动任务扩展留出稳定接口

---

## 1. 结论

当前最合适的方向不是“所有定制都 H5 化”，而是：

**原生负责核心游戏层，H5 负责定制体验层。**

也就是：

- 地图、打点、GPS、指北针、HUD、规则状态机继续原生
- 结算页、文创详情、拍照任务、语音留言、小游戏、品牌包装页交给 H5

---

## 2. 适合 H5 化的内容

当前最适合 H5 承接的是：

- 结算页
- 打点后的定制内容页
- 文创详情页
- 活动品牌页
- 富图文任务页
- 拍照上传 / 语音留言 / 小游戏类互动页
- 表单、问卷、抽奖、作品提交页

不建议 H5 化的部分：

- 地图主界面
- 打点逻辑
- 自动转图
- 指北针
- HUD
- GPS / 心率等实时能力主链
- 需要强实时状态同步的高频游戏弹层

一句话：

**核心实时游戏层保留原生，变化快的定制内容层交给 H5。**

---

## 3. 总体架构

推荐分成三层：

### 3.1 原生层

职责：

- 地图与渲染
- GPS / 指北针 / 自动转图
- 打点状态机
- HUD
- 心率 / telemetry
- 原生内容卡兜底
- 原生结果页兜底
- 核心状态与本地缓存

### 3.2 H5 体验层

职责：

- 定制内容展示
- 品牌包装
- 富交互任务
- 定制结算页
- 富图文与媒体内容

### 3.3 Bridge 层

职责：

- 原生向 H5 注入上下文
- H5 向原生请求能力
- H5 把结果回传原生

---

## 4. 两种 H5 页面类型

### 4.1 Content Experience Page

用于游戏中途的内容体验页。

典型场景：

- 控制点打卡后弹文创详情
- 控制点点击后查看图文内容
- 拍照上传任务
- 语音留言任务
- 小游戏互动页
- 问答/表单类互动页

### 4.2 Result Experience Page

用于游戏结束后的定制结算页。

典型场景：

- 活动定制结算
- 奖章 / 解锁内容
- 排名 / 分享
- 作品提交
- 品牌化结束页

---

## 5. 原生兜底原则

这是最重要的约束。

### 原则 1：核心流程先在原生完成

例如：

- 打点成功必须先由原生确认
- 比赛结束必须先由原生确认
- H5 只是附加体验，不拥有核心状态

### 原则 2：H5 打不开时回退原生

如果：

- 网络失败
- H5 地址失效
- 加载超时
- Bridge 初始化失败

则直接回退：

- 原生内容卡
- 原生结果页

### 原则 3：H5 不控制比赛状态

H5 可以展示、收集信息、提交任务结果。
但不能决定：

- 是否打卡成功
- 是否比赛完成
- 是否跳点成功

这些只能由原生控制。

### 原则 4：H5 是可选增强，不是主流程依赖

即使 H5 没有打开：

- 游戏仍应可继续
- 用户仍能完成路线
- 用户仍能看到最小内容或最小结果

---

## 6. 配置模型建议

后续建议对“内容体验”和“结果体验”都支持两种类型：

- `native`
- `h5`

### 6.1 内容体验配置示例

```json
{
  "contentExperience": {
    "type": "h5",
    "url": "https://example.com/content/control-3",
    "bridge": "content-v1",
    "fallback": "native"
  }
}
```

或：

```json
{
  "contentExperience": {
    "type": "native"
  }
}
```

### 6.2 结果页配置示例

```json
{
  "resultExperience": {
    "type": "h5",
    "url": "https://example.com/result/score-o",
    "bridge": "result-v1",
    "fallback": "native"
  }
}
```

### 6.3 建议扩展字段

后续还可以逐步加入：

- `template`
- `theme`
- `timeoutMs`
- `allowClose`
- `prefetch`
- `requiresNetwork`

---

## 7. 内容页与结果页的推荐职责

### 原生最小内容卡

负责：

- 最小图文说明
- 最小点击查看
- 自动弹出兜底

### H5 内容页

负责：

- 强样式定制
- 多媒体内容
- 任务型互动
- 客户活动包装

### 原生最小结果页

负责：

- 结果一定可见
- 成绩一定可回顾
- 无网络也能展示基础结果

### H5 结果页

负责：

- 品牌化包装
- 排名/分享
- 作品提交
- 奖章、解锁、收集册

---

## 8. 性能与体验要求

H5 接入时必须注意：

- 不阻塞原生主流程
- 不把高频实时状态强行桥接到 H5
- 不在地图进行中频繁开重页面
- 低端机上优先简化交互和媒体资源

推荐策略：

- 内容详情页可以 H5
- 地图中高频反馈继续原生
- 结算增强页可以 H5
- 结果最小摘要必须原生兜底

---

## 9. 当前建议实施顺序

### 第一步

先实现：

- 原生最小兜底内容卡
- 原生最小结果页

### 第二步

新增一个通用 H5 容器页，用于承接：

- 内容页
- 结果页

### 第三步

定义 Bridge 协议，并先支持最核心动作：

- 关闭
- 获取上下文
- 拍照
- 录音
- 提交结果

### 第四步

再让配置决定：

- 当前活动走原生
- 还是走 H5

### 第五步

最后再逐步扩到：

- 上传能力
- 分享能力
- 小游戏任务
- 作品提交

---

## 10. 下一步建议

当前最适合的下一步不是直接写复杂 H5 页面，而是：

1. 先定义原生与 H5 的统一入口模型
2. 先把 Bridge 协议做小而稳
3. 先做一个通用 H5 容器页
4. 先让一个简单内容页或一个简单结果页跑通

---

## 11. 当前建议结论

最稳的方案不是“把定制内容都做成 H5”，而是：

**原生保底，H5 承接定制体验。**

这样既能支持客户高频变化需求，也不会破坏核心游戏体验。

---

## 12. 当前主体能力约束补充

最近实际排查已经确认：

- 当前最初使用的是**个人主体**小程序

在这个前提下，`web-view` 能力可能直接受到限制。  
这意味着：

- H5 页面本身可在浏览器打开
- 小程序里仍然可能无法通过 `web-view` 打开

因此当前 H5 接入方案需要增加一个现实前提：

### 12.1 个人主体下

可以先做：

- 容器页
- Bridge 协议
- 配置结构
- 原生兜底逻辑

但不要指望所有 H5 内容页都能在当前环境稳定跑通。

### 12.2 企业主体下

企业主体审核通过后，再优先回归：

- 最小 `web-view` 测试页
- 内容体验页 H5
- 结果页 H5

也就是说：

当前 H5 方案仍然成立，但在企业主体生效前，应按“预留 + 待验证”看待。

详细说明见：

- [platform-capability-notes.md](D:/dev/cmr-mini/doc/platform-capability-notes.md)