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 必须可降级

因此网站 DEMO 最适合承接：

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

不适合承接：

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

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

参考：

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

必须基于当前已发布 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 条入口：

立即体验
查看活动 DEMO
办活动 / 区域合作

首页模块建议：

品牌首屏
三类用户分流
标准 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 已有能力一致
和未来官网 / 活动门户重构方向一致
不会再造一套和正式系统脱节的“演示站”

colormaprun网站DEMO版方案.md 12 KB Permalink Geschiedenis Ruwe