cmr-mini/doc/gameplay/colormaprun网站DEMO版方案.md

colormaprun 网站 DEMO 版方案

文档版本：v1.0 最后更新：2026-04-07 11:40:54

本文档用于说明 colormaprun.com 在正式重构过程中，是否需要先落一个可对外展示、可内部联调、可逐步演进的 网站 DEMO 版，以及这个 DEMO 应该如何与当前项目已有对象、接口和 H5 方案衔接。

---

1. 总体结论

当前建议：

先做一个“网站 DEMO 版前台”，但不要把它做成浏览器里的完整游戏。

更准确地说，网站 DEMO 应该是：

• 品牌官网的一期可运行版本
• 活动门户的最小公开外壳
• 地图体验入口的只读预览层
• H5 内容增强页的公开承载层
• 小程序 / APP 正式体验链的导流入口

而不应该是：

• 浏览器里复刻完整 GPS 游戏主流程
• 浏览器里承担打点、状态机、计分、对局恢复
• 绕开 EventRelease / runtime / presentation / content bundle 再做一套网站私有数据模型

---

2. 为什么值得先做 DEMO 版

结合当前项目状态，网站 DEMO 版有 4 个现实价值：

2.1 对外可展示

当前线上站点还是静态宣传站，能介绍产品，但不能有效展示：

• 当前有哪些活动
• 默认体验活动是什么
• 一场活动具体长什么样
• 地图、赛道、内容、结果是如何组合的

DEMO 版可以先把这些“真实能力”公开展示出来。

2.2 对内可联调

backend 当前已经有：

• /home
• /cards
• /events/{eventPublicID}
• /events/{eventPublicID}/play
• currentPresentation
• currentContentBundle
• runtime

网站 DEMO 版可以成为这些摘要接口的另一层消费端，不只服务小程序，也服务网站线程。

2.3 对商务和合作更有说服力

当前商务诉求里最难讲清的一件事不是“我们能做地图游戏”，而是：

• 活动门户长什么样
• 客户页面能定制到什么程度
• 地图体验是如何被包装成活动的
• H5 内容页和结果页如何承接品牌方需求

网站 DEMO 版正好可以把这些能力做成可分享链接。

2.4 能平滑演进到正式站点

如果 DEMO 版一开始就沿当前正式对象和正式摘要搭建，那么它后面不需要推倒重来，可以直接逐步升级为：

• 正式官网
• 正式活动门户
• 正式地图体验入口

---

3. 设计前提

这个 DEMO 版必须服从当前项目已经定下来的几个核心边界。

3.1 活动是对外核心，不是地图页

参考：

• APP全局产品架构草案

当前正式产品口径已经明确：

• 地图是资源底座
• 活动是对外核心
• Session 是游戏过程
• 用户资产是长期沉淀

因此网站 DEMO 应该优先承接 Event，而不是直接承接地图运行页。

3.2 网站不拥有核心游戏状态

参考：

• 混合体验架构方案
• H5 增强与内容扩展层方案

当前已经定案：

• 核心游戏过程归原生 / 小程序
• H5 只负责增强体验
• H5 必须可降级

因此网站 DEMO 最适合承接：

• 活动展示
• 地图预览
• H5 内容页
• 结果页样例
• 导流入口

不适合承接：

• GPS 实时主循环
• 打点成功判定
• 比赛开始 / 结束状态推进

3.3 网站必须复用已发布态摘要

参考：

• 后台生产闭环架构草案
• Backend README

当前玩家正式进入规则已经很明确：

• 必须基于当前已发布 EventRelease
• 不能基于 event 草稿默认值
• currentPresentation / currentContentBundle 表示的是已发布 release 实际绑定摘要

网站 DEMO 也应遵守同一条规则。

---

4. 当前项目里已经可复用的能力

当前做网站 DEMO，不需要再从零造一套后台。

4.1 公开卡片摘要

当前可直接复用：

• GET /home
• GET /cards

这些接口已经统一补齐活动卡片最小摘要字段：

• title
• subtitle
• summary
• status
• statusCode
• timeWindow
• ctaText
• coverUrl
• isDefaultExperience
• eventType
• currentPresentation
• currentContentBundle

这已经足够支撑：

• 官网首页活动区
• 活动列表页
• DEMO 活动推荐区

4.2 活动详情摘要

当前可直接复用：

• GET /events/{eventPublicID}

当前最重要的公开摘要包括：

• event
• release
• resolvedRelease
• runtime
• currentPresentation
• currentContentBundle

这已经足够支撑：

• 活动详情页
• DEMO 活动说明页
• 地图预览区
• 内容页入口说明

4.3 标准 demo 活动

当前 backend 已准备三条标准 demo：

• evt_demo_001
• evt_demo_score_o_001
• evt_demo_variant_manual_001

而且它们在 Bootstrap Demo 后都直接具备：

• 当前 release
• runtime
• presentation
• content bundle

这意味着网站 DEMO 版完全可以先围绕这三条标准 demo 起步。

4.4 地图预览思路

参考：

• 准备页地图预览方案

当前已经有非常适合网站 DEMO 的预览策略：

• 使用低级别正式瓦片作为底图
• 使用当前赛道坐标做前端 overlay
• 只做只读预览
• 不做浏览器里的完整交互地图

这套方案天然适合网站详情页和 demo 页。

4.5 H5 内容增强页

当前项目已经明确：

• H5 是独立内容扩展层
• 可以独立发布、独立回滚、独立管理
• 原生永远保底

这意味着网站 DEMO 版可以公开承接：

• 活动包装页
• 内容详情页
• 品牌化结果页样例

---

5. 网站 DEMO 版的推荐定位

当前建议把网站 DEMO 定位成：

“公开活动前台 + 只读体验样板间 + 正式体验导流入口”

可以理解为三层：

5.1 官网层

负责：

• 品牌表达
• 场景说明
• 核心能力介绍
• 商务与合作转化

5.2 活动 DEMO 层

负责：

• 活动卡片列表
• 活动详情
• 活动版本摘要
• 地图预览
• 赛道差异展示
• 内容页 / 结果页样例入口

5.3 正式体验导流层

负责：

• 小程序二维码
• APP 下载
• 默认体验活动导流
• 客户案例和咨询转化

---

6. 当前最推荐的 DEMO 页面结构

6.1 首页 /

首页不只做品牌宣传，建议同时挂出 3 条入口：

1. 立即体验
2. 查看活动 DEMO
3. 办活动 / 区域合作

首页模块建议：

• 品牌首屏
• 三类用户分流
• 标准 demo 活动推荐
• 场景模块
• 核心能力摘要
• 合作与商务 CTA

6.2 活动列表页 /events

建议直接消费 /cards 或 /home 的卡片摘要。

最小结构：

• 顶部说明
• 筛选：
  • 全部
  • 体验活动
  • 进行中
  • 即将开始
  • 已结束
• 卡片列表
• 空状态

这和现有 活动卡片列表最小产品方案 是一致的。

6.3 活动详情页 /events/:eventId

建议直接消费 GET /events/{eventPublicID}。

最小区块：

• 活动主信息
• 当前发布摘要
• 当前地图 / 地点 / 赛道摘要
• 地图预览
• 当前展示版本摘要
• 当前内容包摘要
• CTA：
  • 立即体验
  • 查看内容样例
  • 办同款活动

6.4 DEMO 专题页 /demo

这个页面建议单独保留，不和通用活动列表混在一起。

作用：

• 固定展示三条标准 demo
• 用来对外介绍产品能力边界
• 用来给内部演示和商务沟通发链接

建议固定三个 demo 卡：

• 顺序赛 demo
• 积分赛 demo
• 多赛道 demo

6.5 DEMO 详情页 /demo/:eventId

建议重点展示“这套能力如何组成一场活动”，而不是只展示活动文案。

推荐区块：

• 活动介绍
• 玩法类型
• 地图预览
• 赛道切换预览
• 内容体验样例
• 结果页样例
• 真正体验入口

---

7. DEMO 版应该做什么，不该做什么

7.1 建议做

• 公开活动卡片列表
• 活动详情页
• 只读地图预览
• 多赛道切换预览
• 当前 presentation / content bundle / runtime 摘要说明
• H5 内容页 / 结果页样例跳转
• 导流到 APP / 小程序的正式体验入口

7.2 当前不建议做

• 浏览器里直接起一局正式 session
• 游客在网站里直接体验完整 GPS 游戏
• 网站里实现打点、计分、恢复、结果主链
• 为网站额外定义一套“活动草稿对象”
• 网站直接读取后台草稿对象而不是 release 摘要

7.3 如果一定要做“浏览器可玩的 demo”

当前最稳妥的口径不是“浏览器版正式游戏”，而是：

脚本化演示 demo

即：

• 预录一条轨迹
• 预设几个关键状态
• 演示：
  • 起点
  • 控制点
  • 内容卡
  • 结果页
• 只做播放，不做正式比赛主状态拥有者

这样既能展示玩法，又不破坏当前“核心主流程归原生”的边界。

---

8. DEMO 版的推荐数据挂接方式

8.1 V1

直接使用现有后端摘要接口：

• GET /entry/resolve
• GET /home
• GET /cards
• GET /events/{eventPublicID}

其中建议为网站新增一个固定公开入口 channel，例如：

• website-demo 或
• official-site

这样网站也走“入口上下文首页”逻辑，而不是写死一套站内假数据。

8.2 V1 页面消费原则

网站页面只消费：

• 卡片摘要
• 活动详情摘要
• runtime 摘要
• presentation 摘要
• content bundle 摘要

不消费：

• admin 草稿对象
• build 过程对象
• 原始 KML
• 原始 schema 大对象

8.3 开发态与正式态

开发态可以为了快速联调接：

• /dev/demo-assets/...

但正式 DEMO 页应优先基于：

• 当前已发布 release 摘要
• 当前已发布 currentPresentation
• 当前已发布 currentContentBundle

这样网站 DEMO 才不会和正式发布链分叉。

---

9. 网站 DEMO 的技术落地建议

如果后续需要正式写网站代码，建议在仓库根目录新建：

www/
├─ src/
│  ├─ pages/
│  ├─ components/
│  ├─ features/demo/
│  ├─ features/events/
│  ├─ features/map-preview/
│  ├─ lib/api/
│  ├─ lib/normalizers/
│  └─ lib/mock/
├─ public/
└─ README.md

9.1 当前阶段推荐技术方向

V1 更适合：

• 轻量前台
• 读接口
• 做静态构建
• 做少量交互

因此更推荐：

• www/ 独立站点工程
• 轻量组件化前端
• 以静态页面 + API 拉取为主

当前不建议一开始就做：

• 重 CMS
• 重后台
• 复杂 SSR 体系

9.2 前端层建议拆法

建议把网站前台拆成三层：

页面层

• 首页
• 活动列表页
• 活动详情页
• demo 专题页

领域层

• events
• demo
• map-preview
• lead-forms

数据适配层

负责把 backend 摘要结构适配成网站展示模型，例如：

• CardResult -> SiteEventCard
• EventDetailResult -> SiteEventDetail

这样后端字段后续继续演进时，网站层不会被直接打穿。

---

10. 推荐分阶段实施顺序

第一阶段：网站 DEMO 壳

先做：

• 新首页
• demo 活动推荐区
• 活动列表页
• 活动详情页

这一步先证明：

• 网站已能消费正式活动摘要
• 网站已从纯宣传页升级为活动前台

第二阶段：地图预览与内容样例

再补：

• 地图预览
• 多赛道切换预览
• 内容页 / 结果页样例入口

这一步用来证明：

• 网站能真实展示 runtime / presentation / content bundle 的组合能力

第三阶段：正式体验导流

再补：

• 默认体验入口
• 小程序二维码
• APP 下载和分平台导流
• 商务与合作转化表单

第四阶段：活动门户化

最后再逐步进入：

• 活动专题页
• 地图体验入口页
• 办活动页
• 区域合作页

---

11. 当前最推荐的判断

如果只问一句：

网站上要不要做一个 DEMO 版？

当前答案是：

要做，但这个 DEMO 不是浏览器复刻游戏，而是用正式活动对象、正式发布摘要、只读地图预览和 H5 增强页，做一个可展示、可分享、可联调、可逐步升级成正式门户的网站前台。

这条路线的好处是：

• 和当前项目文档边界一致
• 和当前 backend 已有能力一致
• 和未来官网 / 活动门户重构方向一致
• 不会再造一套和正式系统脱节的“演示站”