整理文档并接入 H5 体验测试链路

doc/content-experience-layer-proposal.md

@@ -0,0 +1,328 @@
+# 游戏中文创体验层方案
+
+## 1. 目标
+
+为游戏过程中的文创内容建立一层独立承载能力，不把内容弹窗、图文卡片、讲解信息散落在：
+
+- 规则层
+- 页面层
+- HUD 逻辑
+- 反馈层
+
+这层的目标是：
+
+- 在正确时机触发内容体验
+- 统一内容展示方式
+- 可配置、可复用、可扩展
+- 不破坏当前地图与规则主链
+
+一句话：
+
+**把“中途内容体验”从临时弹窗提升为正式能力层。**
+
+---
+
+## 2. 当前现状
+
+当前项目已经具备一部分基础：
+
+- `control.displayContent`
+- `UiEffectDirector.showContentCard(...)`
+- 页面层已有 `contentCardVisible / contentCardTitle / contentCardBody`
+- 打点完成后可展示内容卡
+
+这说明：
+
+- 内容展示能力已经有雏形
+- 但触发方式还偏单一
+- 内容形式也还比较轻
+- 还没有形成正式的“内容体验层”模型
+
+---
+
+## 3. 设计原则
+
+### 3.1 内容体验不等于短反馈
+
+短反馈仍然属于：
+
+- 音效
+- 震动
+- HUD 提示
+- 地图 pulse
+
+文创体验属于更重的一层，应与 `FeedbackDirector` 区分。
+
+### 3.2 内容体验不直接写死在规则里
+
+规则层只负责：
+
+- 是否触发
+- 触发什么体验条目
+
+规则层不负责：
+
+- 页面怎么弹
+- 卡片长什么样
+- 是否带图片、音频、讲解按钮
+
+### 3.3 内容体验必须配置驱动
+
+以后不同活动、不同地图、不同玩法需要不同内容。
+
+所以这层必须可配置：
+
+- 哪个点触发
+- 何时触发
+- 弹什么
+- 是否只弹一次
+- 优先级如何
+
+---
+
+## 4. 建议的新层级
+
+建议增加一层：
+
+- `ContentExperienceLayer`
+
+放在概念上与这些层并列：
+
+- `MapPresentation`
+- `HUD`
+- `Feedback`
+- `ResultScene`
+
+职责：
+
+- 接收体验触发
+- 管理当前激活内容项
+- 控制展示与关闭
+- 向页面层输出当前体验模型
+
+---
+
+## 5. 建议的数据模型
+
+### 5.1 ExperienceEntry
+
+```ts
+type ExperienceTrigger =
+  | 'control_completed'
+  | 'zone_entered'
+  | 'session_finished'
+  | 'manual'
+
+type ExperienceDisplayMode =
+  | 'content-card'
+  | 'full-panel'
+  | 'audio-guide'
+  | 'unlock-card'
+
+interface ExperienceEntry {
+  id: string
+  trigger: ExperienceTrigger
+  controlId?: string
+  zoneId?: string
+  title: string
+  body: string
+  imageRef?: string
+  audioRef?: string
+  displayMode: ExperienceDisplayMode
+  once: boolean
+  priority: number
+}
+```
+
+### 5.2 ExperienceRuntimeState
+
+```ts
+interface ExperienceRuntimeState {
+  activeEntryId: string | null
+  dismissedEntryIds: string[]
+  consumedEntryIds: string[]
+}
+```
+
+---
+
+## 6. 配置建议
+
+建议在配置中增加一段：
+
+```json
+{
+  "resources": {
+    "contentEntries": {
+      "cp-3-story": {
+        "title": "校史地标",
+        "body": "这里是校园历史演变的重要节点。",
+        "imageRef": "content/campus-history-01.png",
+        "displayMode": "content-card"
+      }
+    }
+  },
+  "game": {
+    "experience": {
+      "entries": [
+        {
+          "id": "cp-3-story",
+          "trigger": "control_completed",
+          "controlId": "control-3",
+          "once": true,
+          "priority": 10
+        }
+      ]
+    }
+  }
+}
+```
+
+这意味着：
+
+- 资源层管理内容资源
+- 玩法配置决定何时触发
+
+---
+
+## 7. 触发来源
+
+第一阶段建议支持 3 种触发：
+
+### 7.1 打点完成触发
+
+最适合当前项目，价值最高。
+
+例如：
+
+- 完成某个控制点后弹一张文创卡
+- 开始点完成后弹赛事导览卡
+- 终点完成后弹纪念卡
+
+### 7.2 区域进入触发
+
+适合后续：
+
+- 地标介绍
+- 迷雾探索
+- 特定区域故事点
+
+### 7.3 结算后解锁触发
+
+适合后续与结算页联动：
+
+- 收藏卡
+- 奖章
+- 文创奖励
+
+---
+
+## 8. 页面表现建议
+
+第一阶段先做最小闭环，不追求复杂视觉。
+
+### 8.1 第一阶段
+
+支持：
+
+- 当前已有的 `content-card`
+- 标题
+- 正文
+- 关闭
+
+### 8.2 第二阶段
+
+再支持：
+
+- 图片
+- 按钮
+- 章节式展开
+- 音频讲解
+
+---
+
+## 9. 与当前架构的关系
+
+### 规则层
+
+负责：
+
+- 触发某条体验事件
+
+不负责：
+
+- 具体展示细节
+
+### Feedback
+
+继续负责：
+
+- 短反馈
+- 动效
+- 音效
+
+### ContentExperienceLayer
+
+负责：
+
+- 中等时长的信息体验
+
+### 页面层
+
+负责：
+
+- 渲染当前体验模型
+
+---
+
+## 10. 第一阶段最小实施范围
+
+建议第一阶段只做：
+
+1. `control_completed -> experience entry`
+2. `content-card` 展示
+3. `once` 语义
+4. 手动关闭
+5. 配置驱动
+
+不要一上来做：
+
+- 图片轮播
+- 视频
+- 复杂音频控制
+- 多层交互
+
+---
+
+## 11. 推荐实施顺序
+
+1. 定义 `ExperienceEntry`
+2. 在配置解析层接 `game.experience.entries`
+3. 在规则完成事件里派发体验触发
+4. MapEngine 增加体验状态承载
+5. 页面层继续复用当前 `content-card`
+6. 再逐步升级 UI
+
+---
+
+## 12. 长期价值
+
+这层建好后，后续可以自然承接：
+
+- 文创卡片
+- 地标解说
+- 解锁收藏
+- 故事节点
+- 活动内品牌内容
+
+它不只服务当前顺序赛/积分赛，而是服务整条产品体验链。
+
+---
+
+## 13. 结论
+
+当前最正确的方向不是继续在页面里零散补内容弹窗，而是：
+
+**把游戏中途的文创与故事体验正式抽成一层独立的 `ContentExperienceLayer`。**
+
+第一阶段先用“控制点完成触发内容卡”跑通最小闭环，后面再逐步扩成完整体验系统。