mini-prog/doc/hybrid-experience-architecture.md

混合体验架构方案

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

核心结论：

不做“原生还是 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. 推荐的数据流

建议统一做成：

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

这里最关键的是：

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

也就是：

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

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

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

---

6. ViewModel 的作用

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

例如结果页：

{
  "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": "返回地图" }
  ]
}

例如内容页：

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

这样以后无论：

• 原生模板
• 原生 DSL
• H5

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

---

7. 原生模板层建议

建议先做有限几个模板：

结果页模板

• result-minimal
• result-rich

内容页模板

• content-card-minimal
• content-card-story

模板负责：

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

模板不负责：

• 业务逻辑
• 数据计算

---

8. 原生有限 DSL 建议

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

例如结果页：

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

例如内容页：

{
  "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 承担高定制内容。

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