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