# 混合体验架构方案

本文档用于说明当前项目在 **结果页、文创内容页、客户定制体验页** 上的长期承载方案。

核心结论：

**不做“原生还是 H5 二选一”，而是采用三层混合方案：**

- 原生模板
- 原生有限 DSL
- H5 扩展页

当前阶段已经进一步定案：

- **即时内容弹窗：原生**
- **详情页 / 互动任务页：H5**
- **结算页：原生兜底 + H5 全屏增强**

---

## 1. 为什么需要混合方案

当前项目已经确认：

- 结果页经常会变
- 打点弹出内容经常会变
- 样式、内容、交互形式会随着客户需求变化
- 有些内容还会带动作：
  - 拍照上传
  - 语音留言
  - 小游戏
  - 表单与任务

如果全部原生写死：

- 改版成本高
- 每次都要改页面代码
- 客户变化一多就会拖慢开发

如果全部交给 H5：

- 核心体验不稳
- 地图主流程会割裂
- 性能和权限整合更麻烦

因此最适合的方案是：

**核心高频体验保留原生，灵活变化部分分层处理。**

---

## 2. 总体结构

建议未来的体验承载层分成三层：

### 2.1 原生模板层

用于承接：

- 最小结果页
- 最小内容卡
- 高频、必须稳的体验页

特点：

- 结构固定
- 数据可变
- 主题可换
- 性能最好
- 原生能力最完整

### 2.2 原生有限 DSL 层

用于承接：

- 结构变化较多，但组件种类有限的页面
- 结果页区块组合
- 内容页区块组合

特点：

- 不是万能布局引擎
- 只支持有限区块和有限顺序配置
- 比固定模板灵活
- 比 H5 更稳

### 2.3 H5 扩展层

用于承接：

- 强定制内容
- 富图文内容
- 品牌化包装
- 富交互任务页
- 定制结算页

特点：

- 自由度最高
- 改版速度最快
- 最适合客户高频定制
- 但必须有原生兜底

---

## 3. 三层分别适合什么

## 3.1 原生模板适合

- 高频结果页
- 高频内容卡
- 游戏过程中的即时反馈页
- 必须流畅、必须可离线的页面

示例：

- 最小顺序赛结算页
- 最小积分赛结算页
- 控制点原生内容卡
- 默认结束页

## 3.2 原生有限 DSL 适合

- 区块顺序常变
- 字段组合常变
- 样式变化不至于重做到 H5

示例：

- 结果页：
  - 先显示成绩还是先显示摘要
  - 哪些统计项出现
  - 操作区放几个按钮
- 内容页：
  - 是否显示图片
  - 是否显示引用说明
  - 是否显示附加说明区块

## 3.3 H5 适合

- 品牌化结算页
- 长图文故事页
- 原生内容卡上的“查看详情”页
- 拍照上传任务
- 语音留言页
- 小游戏互动页
- 活动专题页
- 高自由度客户定制页

---

## 4. 边界原则

## 4.1 原生负责核心游戏体验

原生必须继续负责：

- 地图
- GPS / 指北针 / 自动转图
- 打点逻辑
- HUD
- 核心状态机
- 最小结果页
- 最小内容页

## 4.2 H5 只负责增强体验

H5 不应该负责：

- 打点是否成功
- 比赛是否结束
- 核心状态推进
- 实时地图交互

H5 只负责：

- 内容展示
- 任务互动
- 品牌包装
- 富交互增强体验

## 4.3 原生永远保底

无论 H5 是否接入，原生都必须保证：

- 打点后至少能看到原生内容
- 结束后至少能看到原生结果页
- H5 打不开时，主流程不受影响

## 4.4 不再尝试 H5 弹窗本体

真机验证后，当前项目已经明确：

- 小程序 `web-view` 不适合作为“原生弹窗里的局部 H5 内容区”
- 它更适合作为整页/全屏体验容器来使用

因此这条边界正式定为：

- 原生内容卡负责即时弹窗体验
- H5 不直接顶替原生弹窗
- H5 只通过原生 CTA 进入详情页/任务页

---

## 5. 推荐的数据流

建议统一做成：

```text
游戏状态 / 内容数据 / 结果数据
        ↓
      ViewModel
        ↓
  Native Template / Native DSL / H5
        ↓
       用户界面
```

这里最关键的是：

- 数据模型稳定
- 展示方式可换

也就是：

**先稳定 ViewModel，再让模板与承载方式变化。**

当前内容体验链已经调整成：

```text
控制点触发
   ↓
原生内容卡（template）
   ↓
CTA: 查看详情（可选）
   ↓
H5 详情页 / 互动任务页
```

---

## 6. ViewModel 的作用

ViewModel 是原生模板、原生 DSL、H5 都共用的中间层。

例如结果页：

```json
{
  "type": "result-summary",
  "title": "比赛结束",
  "subtitle": "校园积分赛",
  "hero": {
    "label": "总分",
    "value": "120"
  },
  "stats": [
    { "key": "duration", "label": "用时", "value": "23:18" },
    { "key": "distance", "label": "里程", "value": "3.2km" },
    { "key": "controls", "label": "完成点", "value": "8/8" }
  ],
  "actions": [
    { "key": "restart", "label": "再来一局" },
    { "key": "close", "label": "返回地图" }
  ]
}
```

例如内容页：

```json
{
  "type": "content-card",
  "title": "湖边步道",
  "body": "这里适合短暂停留观察周边地形。",
  "image": "",
  "cta": "继续"
}
```

这样以后无论：

- 原生模板
- 原生 DSL
- H5

都可以消费同一份结构化数据。

---

## 7. 原生模板层建议

建议先做有限几个模板：

### 结果页模板

- `result-minimal`
- `result-rich`

### 内容页模板

- `content-card-minimal`
- `content-card-story`

模板负责：

- 布局
- 区块顺序
- 基础动画与交互

模板不负责：

- 业务逻辑
- 数据计算

---

## 8. 原生有限 DSL 建议

不要做万能布局引擎，只做有限区块编排。

例如结果页：

```json
{
  "templateType": "result-native-dsl",
  "sections": [
    {
      "type": "hero",
      "field": "score"
    },
    {
      "type": "stats-grid",
      "fields": ["duration", "distance", "controls"]
    },
    {
      "type": "actions",
      "items": ["restart", "close"]
    }
  ]
}
```

例如内容页：

```json
{
  "templateType": "content-native-dsl",
  "sections": [
    { "type": "title" },
    { "type": "body" },
    { "type": "image" },
    { "type": "actions", "items": ["continue", "openH5"] }
  ]
}
```

原则是：

- 区块种类有限
- 顺序可配置
- 不支持无限自由布局

---

## 9. H5 扩展层建议

H5 主要用于高自由度需求。

建议先只承接两类页面：

### 9.1 Content Experience Page

用于：

- 打点后的定制内容页
- 富图文详情
- 拍照上传任务
- 语音留言
- 小游戏互动

### 9.2 Result Experience Page

用于：

- 定制结算页
- 成绩包装页
- 奖章 / 排名 / 分享页

但要注意：

- H5 只是增强页
- 原生始终保留最小兜底

---

## 10. 推荐优先级

不建议直接跳到 H5 大量实现。

推荐顺序：

### 第一步

先把原生模板层打稳：

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

### 第二步

再做原生有限 DSL：

- 支撑中等复杂的客户差异化需求

### 第三步

最后再把 H5 扩展层接稳：

- 处理真正高自由度场景

---

## 11. 对当前项目的建议

结合当前项目现状，建议：

### 当前优先做

- 原生内容卡继续完善
- 原生结果页继续完善
- 先把 ViewModel 定稳

### 中期做

- 原生结果页的有限 DSL
- 原生内容页的有限 DSL

### 后期做

- H5 内容页
- H5 结果页
- Bridge 能力逐步扩充

---

## 12. 一句话结论

最适合当前项目的长期方案不是单押 H5，也不是所有东西都原生写死，而是：

**原生模板保底、原生有限 DSL 承担中度变化、H5 承担高定制内容。**

这三层结合起来，既能保证核心体验稳定，也能承接客户高频变化需求。