# 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全局产品架构草案](D:/dev/cmr-mini/doc/gameplay/APP全局产品架构草案.md)

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

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

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

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

参考：

- [混合体验架构方案](D:/dev/cmr-mini/doc/experience/混合体验架构方案.md)
- [H5 增强与内容扩展层方案](D:/dev/cmr-mini/doc/experience/H5增强与内容扩展层方案.md)

当前已经定案：

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

因此网站 DEMO 最适合承接：

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

不适合承接：

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

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

参考：

- [后台生产闭环架构草案](D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md)
- [Backend README](D:/dev/cmr-mini/backend/README.md)

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

- 必须基于当前已发布 `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 地图预览思路

参考：

- [准备页地图预览方案](D:/dev/cmr-mini/doc/gameplay/准备页地图预览方案.md)

当前已经有非常适合网站 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` 的卡片摘要。

最小结构：

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

这和现有 [活动卡片列表最小产品方案](D:/dev/cmr-mini/doc/gameplay/活动卡片列表最小产品方案.md) 是一致的。

### 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 的技术落地建议

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

```text
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 已有能力一致
- 和未来官网 / 活动门户重构方向一致
- 不会再造一套和正式系统脱节的“演示站”

