# H5 增强与内容扩展层方案
> 文档版本：v1.0
> 最后更新：2026-04-05 12:33:59

本文档用于明确当前项目中，如何通过 **H5 增强层** 承接高变化、高定制的内容与互动需求，同时保证主系统继续保持本地闭环、可降级、可独立管理。

核心结论：

**H5 可以做增强体验，但应作为独立内容扩展层存在；主系统继续持有打点、状态机、结果兜底与核心游戏闭环。**

---

## 1. 目标

本文档重点解决以下问题：

- 如何让 H5 承接详情页、互动任务页、品牌页、增强结果页
- 如何让 H5 与主系统解耦，而不是深度嵌入主流程
- 如何让 H5 页面能够独立开发、独立发布、独立回滚、独立管理
- 如何保证 H5 不可用时，比赛主流程仍然稳定可用

适用场景：

- 打点后的详情说明页
- 打点后的互动任务页
- 拍照、录音、留言、作品提交等扩展页
- 品牌化结果页与活动包装页

不适用场景：

- 地图主界面
- 打点判定
- 比赛开始 / 进行中 / 结束状态推进
- 高频实时 telemetry 主链路

---

## 2. 设计原则

### 2.1 主系统本地闭环

必须继续由小程序 / 原生层负责：

- 地图与定位
- 打点判定
- 核心状态机
- 最小内容卡
- 最小结果页
- 本地缓存与断网兜底

### 2.2 H5 只做增强，不做状态拥有者

H5 适合负责：

- 富图文详情
- 互动任务
- 品牌包装
- 表单与作品提交
- 增强结果页

H5 不直接决定：

- 是否打点成功
- 是否比赛结束
- 是否跳点成功
- 是否修改核心规则状态

### 2.3 H5 必须独立存在

H5 页面不应作为“主系统页面的一部分代码”长期散落在业务仓里，而应逐步具备以下能力：

- 独立页面目录与版本
- 独立静态资源发布
- 独立主题与资源管理
- 独立入口配置
- 独立回滚

### 2.4 契约优先于页面实现

主系统与 H5 之间优先约定：

- 页面入口模型
- Bridge 协议版本
- 页面能力白名单
- 结果回传结构
- fallback 行为

而不是先做大量页面，再反向补协议。

### 2.5 所有增强能力都必须可降级

若 H5 打不开、Bridge 不可用、内容面 API 失败，系统应自动降级为：

- 仍显示原生内容卡
- 仍可继续比赛
- 仍可查看原生结果页
- 不阻断地图主流程

---

## 3. 推荐分层

建议当前项目的体验承载层按四层理解：

### 3.1 核心游戏层

负责：

- 打点
- 地图
- GPS
- HUD
- 规则引擎
- 结果结算

这一层不依赖 H5 才能成立。

### 3.2 原生兜底体验层

负责：

- 最小内容卡
- 最小结果页
- 必要 CTA
- H5 失败时的替代展示

### 3.3 H5 内容扩展层

负责：

- 详情页
- 互动任务页
- 品牌活动页
- 增强结果页

这一层通过原生 CTA 进入，不再承担局部弹窗职责。

### 3.4 内容管理与发布层

负责：

- H5 页面入口管理
- 页面版本管理
- Bridge 白名单管理
- 主题与资源管理
- fallback 策略
- 页面发布与回滚

这一层建议长期从玩法主配置中拆出来，形成独立内容体验管理能力。

---

## 4. 推荐页面类型

建议第一阶段只正式支持以下几类 H5 页面：

### 4.1 内容详情页

用于：

- 打点后的补充说明
- 景点 / 点位图文介绍
- 活动详情说明

特点：

- 展示为主
- 交互较轻
- 可由原生内容卡 CTA 进入

### 4.2 互动任务页

用于：

- 拍照打卡
- 语音留言
- 问答互动
- 收集式任务
- 轻量小游戏互动

特点：

- 需要 Bridge 能力
- 需要任务结果回传
- 需要原生 fallback

### 4.3 增强结果页

用于：

- 品牌化成绩包装
- 徽章 / 分享 / 排名增强
- 作品提交后展示

特点：

- 原生结果页始终保底
- H5 只做增强版入口

### 4.4 活动包装页

用于：

- 活动专题
- 客户品牌包装
- 招募 / 说明 / 规则展示

特点：

- 可独立于局内主链存在
- 更接近内容页，而非玩法页

---

## 5. 推荐运行链路

对于“打点后增强体验”，建议统一为：

```text
完成打点
-> 原生判定成功
-> 原生内容卡 / 原生短反馈
-> 用户点击 CTA
-> 打开整页 H5 详情页 / 任务页
-> H5 获取上下文并完成互动
-> H5 submitResult 回传结果
-> 原生决定后续反馈 / 结果展示
```

对于“活动浏览链路”，建议统一为：

```text
活动列表
-> 活动详情页
-> 准备页
-> 地图主链
-> 原生结果页
-> 可选进入 H5 增强结果页
```

关键点：

- H5 总是在主系统之后进入，而不是反向驱动主系统
- 打点成功必须先由原生确认
- 结果页必须始终有原生版本兜底

---

## 6. 推荐配置挂接方式

当前项目建议继续沿用现有配置口径：

- `playfield.controlOverrides.<key>.autoPopup`
- `playfield.controlOverrides.<key>.contentExperience`
- `playfield.controlOverrides.<key>.clickExperience`

推荐理解：

- `autoPopup`
  控制打点完成后是否先弹原生内容卡
- `contentExperience`
  控制打点成功后的扩展体验入口
- `clickExperience`
  控制点击点位时的补充内容入口

建议最小配置示例：

```json
{
  "playfield": {
    "controlOverrides": {
      "control-3": {
        "autoPopup": true,
        "contentExperience": {
          "type": "h5",
          "url": "https://example.com/h5/tasks/control-3",
          "bridge": "content-v1",
          "presentation": "fullscreen"
        }
      }
    }
  }
}
```

建议继续坚持：

- 不让 H5 直接顶替原生即时内容弹窗
- H5 默认按整页 / 全屏容器打开
- 配置只声明入口，不让页面内部细节反向污染玩法主配置

---

## 7. 推荐 Bridge 最小契约

H5 与主系统之间建议继续保持最小协议：

### 7.1 原生注入上下文

最少应包含：

- `eventId`
- `sessionId`
- `sessionStatus`
- `controlId`
- `bridgeVersion`
- `mode`
- `title`
- `theme`

### 7.2 H5 可请求的最小能力

第一阶段建议只开放：

- `getGameContext`
- `close`
- `takePhoto`
- `recordAudio`
- `submitResult`

### 7.3 H5 回传结果的最小结构

建议最少包含：

- `taskId`
- `status`
- `payload`

示例：

```json
{
  "id": "req-002",
  "channel": "request",
  "type": "submitResult",
  "payload": {
    "taskId": "task-photo-control-3",
    "status": "completed",
    "payload": {
      "assetId": "img-001"
    }
  }
}
```

### 7.4 协议边界

Bridge 只做：

- 上下文读取
- 能力请求
- 结果回传

Bridge 不做：

- 比赛核心状态修改
- 打点成功与否判定
- 比赛结束判定
- 地图主循环控制

---

## 8. 推荐独立管理方式

若希望 H5 真正可扩展、可维护，建议长期形成独立内容体验管理能力。

### 8.1 管理对象

建议至少管理以下对象：

- 页面入口对象
- 页面版本对象
- 页面主题对象
- 页面资源对象
- Bridge 能力白名单
- fallback 策略

### 8.2 与活动对象的关系

建议活动只绑定“已发布的体验对象摘要”，而不直接持有散装页面地址。

推荐关系：

```text
Event
-> EventRelease
-> currentPresentation
-> currentContentBundle
-> runtime
-> H5 页面入口摘要 / 任务入口摘要
```

### 8.3 与后台的分工

建议在后台中单列“内容体验中心”，负责：

- 原生模板
- 原生 DSL
- H5 页面入口
- Bridge 能力
- 主题配置
- 资源配置
- fallback 策略

而不是让玩法后台直接承接所有 H5 页面细节。

---

## 9. 推荐发布与部署方式

H5 增强层建议按“独立静态发布物”管理。

### 9.1 页面交付形态

建议：

- H5 页面资源走静态发布物
- 上传 OSS / CDN
- 由主系统根据已发布入口打开

### 9.2 版本策略

建议每个 H5 页面具备：

- 页面编码 `pageCode`
- 页面版本 `version`
- 协议版本 `bridgeVersion`
- 状态 `draft / published / archived`

### 9.3 回滚策略

建议 H5 页面支持：

- 单页回滚
- 活动级解绑
- fallback 到原生页

这样可以做到：

- 内容改版不必改主系统发版
- 某个 H5 页出问题时可快速下线
- 玩法主链不受拖累

---

## 10. 推荐 fallback 策略

建议从一开始就明确这几类降级行为：

### 10.1 H5 页面打不开

- 回退到原生内容卡
- 允许继续比赛

### 10.2 Bridge 不可用

- 禁用扩展能力按钮
- 保留基础图文展示

### 10.3 内容面 API 异常

- 允许 H5 本地完成基础展示
- 结果回传失败时提示稍后重试或改走原生兜底

### 10.4 增强结果页不可用

- 保底显示原生结果页
- 不影响本局成绩结算与查看

---

## 11. 对当前项目的建议落地顺序

建议按以下顺序推进，而不是一开始就大规模铺 H5 页：

### 第一阶段：定住边界

- 固定“原生内容卡 + H5 整页任务页”口径
- 固定 `content-v1` / `result-v1`
- 固定 fallback 规则

### 第二阶段：跑通最小闭环

- 先跑通一个内容详情页
- 再跑通一个互动任务页
- 再跑通一个增强结果页入口

### 第三阶段：独立化管理

- 抽出 H5 页面入口管理
- 抽出 Bridge 白名单管理
- 抽出页面版本与发布记录

### 第四阶段：产品化扩展

- 再接拍照任务
- 再接留言任务
- 再接作品提交
- 再接品牌专题与增强结果页

---

## 12. 当前阶段不建议做的事

- 不建议继续尝试局部 H5 弹窗
- 不建议让 H5 直接参与打点判定
- 不建议让 H5 持有比赛主状态
- 不建议把 H5 页面地址直接散落在多个业务字段里长期维护
- 不建议把页面内部所有细节都硬塞进玩法主配置
- 不建议在没有 fallback 的前提下把结果页完全交给 H5

---

## 13. 与现有文档的关系

本方案是对以下文档的补充收口：

- `混合体验架构方案`
- `原生与 H5 Bridge 规范`
- `主流程与增强能力边界说明`
- `API 与发布物边界约定`
- `后台管理系统建设建议`

定位上：

- `混合体验架构方案` 负责总体分层
- `Bridge 规范` 负责通信契约
- 本文负责回答“H5 如何作为独立增强层长期存在并管理”

---

## 14. 一句话结论

最适合当前项目的 H5 方案，不是把 H5 做成主系统的一部分，而是：

**主系统持有核心闭环，H5 作为独立内容扩展层存在，通过稳定入口、稳定 Bridge、独立发布和明确 fallback 承接高变化体验。**