推进活动系统最小成品闭环与游客体验

2026-04-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
--- a/doc/gameplay/colormaprun网站DEMO版方案.md
+++ b/doc/gameplay/colormaprun网站DEMO版方案.md
@@ -0,0 +1,597 @@
+# 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 已有能力一致
+- 和未来官网 / 活动门户重构方向一致
+- 不会再造一套和正式系统脱节的“演示站”
+