docs: add h5 experience and tracking specs

doc/experience/H5任务页埋点与结果回传规范.md

@@ -0,0 +1,641 @@
+# H5 任务页埋点与结果回传规范
+> 文档版本：v1.0
+> 最后更新：2026-04-05 12:36:25
+
+本文档用于定义当前项目中，**原生内容卡、H5 详情页、H5 互动任务页、增强结果页** 的最小埋点口径与结果回传结构，避免后续出现“曝光、点击、任务完成、业务落库”混为一谈的情况。
+
+核心结论：
+
+**展示埋点、交互埋点、任务结果回传必须分层定义；H5 可以上报行为与任务结果，但不能直接决定打点成功或比赛状态。**
+
+---
+
+## 1. 目标
+
+本文档重点解决以下问题：
+
+- 如何统一原生内容卡与 H5 页的埋点事件口径
+- 如何区分“浏览行为”与“任务完成结果”
+- 如何通过 `submitResult` 回传 H5 任务页结果
+- 如何让内容面 API 稳定承接任务结果落库
+- 如何保证埋点失败或回传失败时不阻断主流程
+
+适用范围：
+
+- 打点后原生内容卡
+- 原生内容卡 CTA 进入的 H5 详情页
+- H5 互动任务页
+- H5 增强结果页
+
+不适用范围：
+
+- 打点判定本身
+- 地图主链状态流转
+- 高频 telemetry 主链
+- 实时网关事件流替代方案
+
+---
+
+## 2. 边界原则
+
+### 2.1 任务结果不等于比赛结果
+
+H5 回传的任务结果只表示：
+
+- 某个互动任务是否完成
+- 某个表单是否提交
+- 某个作品是否生成
+- 某个增强页是否完成关键动作
+
+它不直接表示：
+
+- 打点是否成功
+- 本局是否完赛
+- 成绩是否生效
+
+### 2.2 埋点事件不等于业务落库
+
+埋点事件主要用于：
+
+- 行为分析
+- 页面漏斗观察
+- 体验优化
+- 运营数据统计
+
+业务落库主要用于：
+
+- 记录任务完成事实
+- 记录作品或表单提交结果
+- 记录奖励发放依据
+
+这两者可以共用部分字段，但不能视为同一条链路。
+
+### 2.3 埋点失败不阻断体验
+
+若埋点上报失败：
+
+- 页面仍可继续浏览
+- 任务仍可继续操作
+- 比赛主流程不应被中断
+
+### 2.4 结果回传失败不反向控制主流程
+
+若 `submitResult` 或内容面 API 落库失败：
+
+- 不应改写打点成功状态
+- 不应强制比赛中断
+- 允许重试、缓存或降级提示
+
+---
+
+## 3. 推荐分层模型
+
+建议将相关事件分为三层：
+
+### 3.1 展示层事件
+
+用于记录页面或卡片是否被看到。
+
+例如：
+
+- 内容卡进入
+- H5 页面曝光
+- 结果页进入
+
+### 3.2 交互层事件
+
+用于记录用户在页面中的关键操作。
+
+例如：
+
+- CTA 点击
+- 页面关闭
+- 按钮点击
+- 表单提交点击
+- 分享点击
+
+### 3.3 结果层事件
+
+用于记录任务是否完成，以及完成后产出的结果对象。
+
+例如：
+
+- 拍照任务完成
+- 留言任务完成
+- 答题任务完成
+- 作品提交成功
+
+---
+
+## 4. 统一标识字段
+
+无论是原生内容卡还是 H5 页面，建议统一携带以下字段：
+
+- `eventId`
+  活动标识
+- `sessionId`
+  对局标识
+- `controlId`
+  点位标识；非点位页面可为空
+- `taskId`
+  任务标识；非任务页面可为空
+- `pageCode`
+  H5 页面编码
+- `pageType`
+  页面类型
+- `bridgeVersion`
+  Bridge 协议版本
+- `contentSource`
+  内容来源
+- `triggerSource`
+  触发来源
+- `timestamp`
+  事件时间
+
+建议补充字段：
+
+- `userId`
+- `tenantId`
+- `variantId`
+- `resultId`
+- `deviceType`
+- `networkType`
+
+字段说明：
+
+- `contentSource`
+  建议取值：`native-card` `h5-content` `h5-task` `h5-result`
+- `triggerSource`
+  建议取值：`auto-popup` `card-cta` `map-click` `result-action`
+
+---
+
+## 5. 页面类型建议
+
+建议统一定义以下 `pageType`：
+
+- `native-content-card`
+- `h5-content-page`
+- `h5-task-page`
+- `native-result-page`
+- `h5-result-page`
+
+这样可以保证：
+
+- 原生与 H5 事件可以统一分析
+- 同一任务可横跨内容卡和任务页追踪
+- 结果页增强链不会混进地图主链事件
+
+---
+
+## 6. 原生内容卡最小事件集
+
+结合当前待办中的口径，建议先正式收口以下事件：
+
+### 6.1 `content_card_enter`
+
+表示内容卡实际展示给用户。
+
+建议时机：
+
+- 卡片完成入场动画后
+- 卡片真实可见时
+
+### 6.2 `content_card_close`
+
+表示内容卡被关闭。
+
+建议补充原因字段：
+
+- `closeReason = auto-dismiss`
+- `closeReason = user-close`
+- `closeReason = replaced`
+- `closeReason = open-h5`
+
+### 6.3 `content_card_cta_click`
+
+表示用户点击内容卡主 CTA。
+
+建议补充字段：
+
+- `ctaKey`
+- `targetType`
+- `targetPageCode`
+
+### 6.4 `result_page_enter`
+
+表示原生结果页进入。
+
+该事件用于与 H5 增强结果页做漏斗对比。
+
+---
+
+## 7. H5 页面最小事件集
+
+### 7.1 `h5_page_enter`
+
+表示 H5 页面真实进入。
+
+建议在：
+
+- 页面初始化完成
+- 基础上下文已拿到
+- 主视图可见
+
+之后触发，而不是在 `web-view` 打开瞬间就记。
+
+### 7.2 `h5_page_exit`
+
+表示 H5 页面退出。
+
+建议补充：
+
+- `exitReason = close`
+- `exitReason = back`
+- `exitReason = bridge-close`
+- `exitReason = replaced`
+- `exitReason = error`
+
+### 7.3 `h5_cta_click`
+
+表示 H5 页内关键 CTA 被点击。
+
+建议至少带：
+
+- `ctaKey`
+- `ctaLabel`
+- `taskId`
+
+### 7.4 `h5_interaction`
+
+表示任务页关键互动动作。
+
+建议只用于关键动作，不记录所有噪声操作。
+
+推荐 `actionKey`：
+
+- `start-task`
+- `take-photo`
+- `record-audio`
+- `submit-form`
+- `share`
+- `retry`
+
+---
+
+## 8. 任务生命周期事件
+
+若页面属于互动任务页，建议增加一组任务态事件：
+
+### 8.1 `task_viewed`
+
+表示用户已看到任务主体。
+
+### 8.2 `task_started`
+
+表示用户开始任务，不再只是浏览。
+
+### 8.3 `task_progressed`
+
+表示阶段性推进。
+
+适用场景：
+
+- 多步表单
+- 连续拍照
+- 多题答题
+- 分阶段收集
+
+建议带：
+
+- `stepId`
+- `stepIndex`
+- `stepStatus`
+
+### 8.4 `task_completed`
+
+表示任务完成，但不代表业务一定已成功落库。
+
+### 8.5 `task_failed`
+
+表示任务失败。
+
+建议补充：
+
+- `errorCode`
+- `errorStage`
+
+### 8.6 `task_cancelled`
+
+表示用户主动放弃任务。
+
+---
+
+## 9. `submitResult` 推荐结构
+
+建议将 `submitResult` 视为“结果层回传”，而不是普通点击埋点。
+
+推荐最小结构：
+
+```json
+{
+  "id": "req-002",
+  "channel": "request",
+  "type": "submitResult",
+  "payload": {
+    "taskId": "task-photo-control-3",
+    "taskType": "photo-checkin",
+    "attemptId": "attempt-001",
+    "status": "completed",
+    "pageCode": "task-control-3-photo",
+    "controlId": "control-3",
+    "result": {
+      "assetId": "img-001"
+    }
+  }
+}
+```
+
+字段建议：
+
+- `taskId`
+  任务标识
+- `taskType`
+  任务类型
+- `attemptId`
+  一次任务尝试标识
+- `status`
+  任务结果状态
+- `pageCode`
+  页面编码
+- `controlId`
+  关联点位
+- `result`
+  结构化结果对象
+
+---
+
+## 10. `submitResult.status` 建议口径
+
+建议第一阶段只正式支持：
+
+- `completed`
+- `failed`
+- `cancelled`
+- `skipped`
+
+建议解释：
+
+- `completed`
+  用户已完成任务目标
+- `failed`
+  本次任务尝试失败
+- `cancelled`
+  用户主动退出或放弃
+- `skipped`
+  允许跳过的任务被明确跳过
+
+当前不建议第一阶段就把过多中间状态做成业务落库状态。
+
+例如：
+
+- `viewed`
+- `started`
+- `progressed`
+
+这些更适合作为埋点事件，而不是最终任务结果状态。
+
+---
+
+## 11. `result` 结果对象建议
+
+不同任务类型建议分别约定 `result`：
+
+### 11.1 拍照任务
+
+```json
+{
+  "assetId": "img-001",
+  "assetType": "image",
+  "count": 1
+}
+```
+
+### 11.2 录音任务
+
+```json
+{
+  "assetId": "audio-001",
+  "assetType": "audio",
+  "durationMs": 12000
+}
+```
+
+### 11.3 表单任务
+
+```json
+{
+  "formId": "form-001",
+  "submissionId": "sub-001"
+}
+```
+
+### 11.4 问答任务
+
+```json
+{
+  "questionSetId": "quiz-001",
+  "score": 3,
+  "total": 5
+}
+```
+
+原则：
+
+- `result` 保持结构化
+- 不直接塞整页原始页面状态
+- 不把分析事件数组混进 `result`
+
+---
+
+## 12. 内容面 API 落库建议
+
+建议内容面 API 承接：
+
+- H5 页面入口鉴权
+- H5 上下文初始化
+- `submitResult` 后的业务落库
+- 上传结果对象登记
+
+建议最小落库对象至少包含：
+
+- `eventId`
+- `sessionId`
+- `controlId`
+- `taskId`
+- `attemptId`
+- `pageCode`
+- `status`
+- `resultJson`
+- `submittedAt`
+
+建议能力边界：
+
+- 内容面 API 记录任务完成事实
+- 主系统继续负责比赛核心状态
+- 不通过内容面 API 直接判定打点成功或比赛结束
+
+---
+
+## 13. 去重与幂等建议
+
+为避免重复点击、网络重试或页面重进导致重复落库，建议：
+
+### 13.1 任务尝试幂等
+
+建议以：
+
+- `sessionId`
+- `taskId`
+- `attemptId`
+
+作为一次任务尝试的幂等键。
+
+### 13.2 埋点去重
+
+建议以下事件在单次页面进入内只记一次：
+
+- `h5_page_enter`
+- `task_viewed`
+- `task_started`
+- `task_completed`
+
+### 13.3 可重复事件
+
+以下事件允许多次：
+
+- `h5_cta_click`
+- `h5_interaction`
+- `task_progressed`
+
+但建议带：
+
+- `sequence`
+- `stepId`
+- `timestamp`
+
+---
+
+## 14. 推荐上报时机
+
+建议的最小时机如下：
+
+### 14.1 原生内容卡
+
+- 卡片入场完成后：`content_card_enter`
+- 用户关闭时：`content_card_close`
+- CTA 点击时：`content_card_cta_click`
+
+### 14.2 H5 内容页 / 任务页
+
+- 页面首屏稳定后：`h5_page_enter`
+- 任务主体真正可见后：`task_viewed`
+- 用户开始实际互动后：`task_started`
+- 关键阶段完成后：`task_progressed`
+- 调用 `submitResult(completed)` 前：`task_completed`
+
+### 14.3 结果页
+
+- 原生结果页进入：`result_page_enter`
+- H5 增强结果页进入：`h5_page_enter`
+
+---
+
+## 15. fallback 规则
+
+### 15.1 H5 打不开
+
+- 记一条 `h5_open_failed`
+- 回退到原生内容卡或原生结果页
+
+### 15.2 埋点接口失败
+
+- 允许静默失败或批量补报
+- 不阻断用户当前操作
+
+### 15.3 `submitResult` 失败
+
+- 页面应拿到明确失败回执
+- 允许用户重试
+- 原生可决定是否保留最小完成提示
+
+### 15.4 Bridge 未就绪
+
+- 禁用依赖原生能力的操作
+- 仅保留静态浏览能力
+
+---
+
+## 16. 第一阶段建议收口的正式事件
+
+建议第一阶段只先正式收口以下事件，不一开始扩太大：
+
+- `content_card_enter`
+- `content_card_close`
+- `content_card_cta_click`
+- `result_page_enter`
+- `h5_page_enter`
+- `h5_page_exit`
+- `h5_cta_click`
+- `task_viewed`
+- `task_started`
+- `task_completed`
+- `task_failed`
+- `task_cancelled`
+
+以及一个正式回传动作：
+
+- `submitResult`
+
+这样已经足够支撑：
+
+- 内容卡漏斗
+- H5 页面进入漏斗
+- 任务页完成率
+- 原生页与 H5 页联动链路
+
+---
+
+## 17. 当前阶段不建议做的事
+
+- 不建议把所有按钮点击都做成正式公共事件
+- 不建议把页面内局部滚动、每次切 tab 都纳入统一业务口径
+- 不建议让 `submitResult` 兼做曝光埋点
+- 不建议让 H5 页面自己定义完全不同的一套事件命名
+- 不建议直接把原始页面表单全文落到统一分析事件里
+
+---
+
+## 18. 与现有文档的关系
+
+本规范补充收口以下文档中的未定项：
+
+- `原生与 H5 Bridge 规范`
+- `H5 增强与内容扩展层方案`
+- `混合体验架构方案`
+- `API 与发布物边界约定`
+- `MyToDo` 中已出现的内容卡与结果页事件线索
+
+定位上：
+
+- `Bridge 规范` 负责通信动作
+- 本文负责埋点口径与任务结果口径
+- 内容面 API 文档后续再细化具体落库接口
+
+---
+
+## 19. 一句话结论
+
+最适合当前项目的做法不是让 H5 自己发明一套任务体系，而是：
+
+**由主系统定义统一上下文、统一事件口径、统一结果回传结构，让 H5 只负责增强体验与任务执行。**

doc/experience/H5增强与内容扩展层方案.md

@@ -0,0 +1,536 @@
+# 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 承接高变化体验。**

doc/文档索引.md

@@ -1,6 +1,6 @@
 # 文档索引
-> 文档版本：v1.6
-> 最后更新：2026-04-03 22:05:00
+> 文档版本：v1.8
+> 最后更新：2026-04-05 12:36:25
 
 维护约定：
 
@@ -63,6 +63,8 @@
 
 - [混合体验架构](/D:/dev/cmr-mini/doc/experience/混合体验架构方案.md)
 - [原生与 H5 Bridge 规范](/D:/dev/cmr-mini/doc/experience/原生与H5桥接规范.md)
+- [H5 增强与内容扩展层方案](/D:/dev/mini-prog/doc/experience/H5增强与内容扩展层方案.md)
+- [H5 任务页埋点与结果回传规范](/D:/dev/mini-prog/doc/experience/H5任务页埋点与结果回传规范.md)
 
 ## 渲染
 
@@ -89,5 +91,3 @@
 
 - 长期保留的少量工作便签见 [notes](/D:/dev/cmr-mini/doc/notes)。
 - 历史方案稿和阶段性讨论稿已移到 [archive](/D:/dev/cmr-mini/doc/archive/归档索引.md)。
-
-