zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
zhangyan
2026-04-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
Download Patch File Download Diff File Expand all files Collapse all files

597
doc/gameplay/colormaprun网站DEMO版方案.md Normal file
View File

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

223
doc/gameplay/colormaprun网站重构方案.md Normal file
View File

@@ -0,0 +1,223 @@
# colormaprun 网站重构方案
> 文档版本：v1.0
> 最后更新：2026-04-07 10:32:36
本文档用于整理 `colormaprun.com` 的重构方向，明确其从宣传官网升级为“品牌官网 + 活动门户 + 地图体验入口 + 商务转化站”的产品基线，并作为后续网站线程实施的正式依据。
---
## 1. 当前定位判断
当前 `colormaprun.com` 已经不只是 APP 下载页，而是同时承担了三种角色：
1. C 端玩家体验入口
2. B 端活动/赛事服务展示入口
3. 区域合作与商务转化入口
因此，重构不应停留在“视觉改版”，而应升级为完整的网站产品重构。
---
## 2. 重构目标
重构后的站点应同时承担：
### 2.1 品牌官网
负责：
- 品牌表达
- 核心能力展示
- 产品可信度
- 合作案例与合作伙伴
### 2.2 活动门户
负责：
- 活动列表
- 活动详情
- 报名/签到/排行榜等活动入口
- 默认体验活动入口
### 2.3 地图体验入口
负责：
- 地区与地图入口
- 默认体验活动
- 地图预约
- 体验链路承接
### 2.4 商务转化站
负责：
- 校园活动
- 企业团建
- 亲子活动
- 专业赛事
- 区域合作
---
## 3. 三类核心用户
网站重构必须按用户类型分流：
### 3.1 玩家
关注：
- 我能玩什么
- 附近或推荐地图
- 默认体验活动
- 下载与快速开始
### 3.2 活动组织者 / 客户
关注：
- 能承接什么类型活动
- 方案能力
- 案例
- 联系与咨询
### 3.3 区域合作方
关注：
- 合作模式
- 权益与边界
- 区域机会
- 商务联系
---
## 4. 一级信息架构建议
建议重构后站点至少包含以下一级结构：
1. 首页
2. 活动
3. 地图体验
4. 办活动
5. 区域合作
6. 帮助与课堂
---
## 5. 首页改造方向
首页不再做单一宣传页，而改成“分流首页”。
首屏建议直接提供三类主 CTA：
- 立即体验
- 办活动 / 赛事
- 区域合作
同时保留：
- APP 下载入口
- 品牌差异化能力
- 核心场景
- 合作背书
---
## 6. 活动门户方向
活动是后续网站最重要的一层。
建议后续网站活动模块包括：
- 活动列表页
- 活动详情页
- 活动专题页
- 默认体验活动入口
要求：
- 活动展示来自后台生产与发布系统
- 兼容标准活动与定制活动
- 不把活动系统固化成几个死模板
---
## 7. 地图体验入口方向
地图入口负责承接：
- 地区浏览
- 地图浏览
- 默认活动体验
- 地图预约
地图预约页应被视为：
- 需求捕获页
- 地图供给扩张入口
- 区域合作潜在线索入口
---
## 8. 办活动与合作页方向
### 8.1 办活动
建议聚焦：
- 校园活动
- 企业团建
- 亲子研学
- 专业赛事
### 8.2 区域合作
建议聚焦：
- 合作模式
- 区域权益
- 共建模式
- 商务联系
---
## 9. 与后台生产系统的关系
网站后续不应长期停留在静态维护，而应逐步与后台生产系统打通：
- 活动列表来自 `Event / EventRelease`
- 活动详情来自 `EventPresentation / ContentBundle`
- 地图体验入口来自默认活动和地图资源
- 商务页与内容页仍可保留部分静态编排
---
## 10. 推荐实施顺序
### 第一阶段
- 首页分流重构
- 活动列表/详情最小门户化
- 办活动页
- 合作页
### 第二阶段
- 地图体验页
- 课堂 / FAQ / 手册与转化路径重组
### 第三阶段
- 与后台生产和发布系统进一步动态打通
- 统计和转化数据化
---
## 11. 一句话结论
`colormaprun.com` 的重构目标，不是简单换皮，而是升级成：
**品牌官网 + 活动门户 + 地图体验入口 + 商务转化站。**

388
doc/gameplay/准备页地图预览方案.md Normal file
View File

@@ -0,0 +1,388 @@
# 准备页地图预览方案
> 文档版本：v1.0
> 最后更新：2026-04-07 12:18:00
本文档用于说明活动准备页的地图预览能力如何设计与落地。
当前目标不是直接进入实现，而是先把方案边界、分层、前后端职责和分阶段路径定清。
---
## 1. 目标
准备页当前已经具备：
- 活动状态摘要
- 赛道选择
- 设备准备
- 进入地图
但“本局对象预览”仍然主要是文字占位，对玩家帮助有限。
准备页地图预览的目标是：
1. 在进入地图前，让玩家建立空间预期
2. 在多赛道活动中，让玩家能直观看到当前赛道差异
3. 让准备页更像“出发前准备”，而不是工程参数页
4. 不打断当前 runtime 主链，也不额外制造一套重资源地图体系
---
## 2. 推荐方案
当前推荐采用：
**低级别正式瓦片做底图，前端动态叠加赛道**
也就是：
- 底图来源：现有正式瓦片资源
- 底图级别：选择一个较低 zoom 作为预览缩略底图
- 叠加层：前端根据当前赛道数据在预览图上动态绘制起点、终点、控制点和腿线
这是一个“混合预览方案”：
- 不单独制作新的预览地图资源
- 不在前端完整拼装高精度交互地图
- 只在准备页做只读预览
---
## 3. 为什么选这个方案
### 3.1 不新增独立地图资源
如果单独为准备页制作预览地图资源，会带来：
- 资源重复
- 发布链复杂度上升
- 底图与正式地图不一致风险
使用低级别正式瓦片作为预览底图，可以保持：
- 同源
- 一致
- 低成本
### 3.2 多赛道切换更自然
多赛道场景下：
- 底图通常是同一张地图
- 差异主要在赛道叠加层
因此最合理的方式是：
- 底图固定
- 切换赛道时仅重绘 overlay
这样：
- 切换更快
- 数据结构更清楚
- 不需要为每个 variant 重新生成整张预览图
### 3.3 前后端职责清楚
后端负责：
- 提供底图预览所需元数据
- 提供赛道叠加所需坐标数据
前端负责：
- 展示底图
- 动态叠加赛道
- 在准备页进行只读预览
这符合当前项目一直坚持的分层原则。
---
## 4. 整体分层
准备页地图预览建议分成 4 层。
### 4.1 地图底图层
来源：
- 当前正式瓦片资源
形式：
- 低级别缩略底图
职责：
- 提供地点区域的空间背景
### 4.2 预览元数据层
来源：
- 后端预览元数据
职责：
- 告诉前端如何把经纬度投到预览图坐标系中
### 4.3 赛道叠加层
来源：
- variant 控制点与腿线数据
职责：
- 在准备页上画出当前赛道
### 4.4 准备页展示层
职责：
- 只读展示
- 切换赛道联动预览
- 不承担局内交互
---
## 5. 后端需要提供的最小字段
V1 不要求后端提供完整预览图 URL，而是先提供“底图元数据 + 赛道 overlay 元数据”。
建议后端提供以下最小结构：
```json
{
"preview": {
"mode": "full",
"baseTiles": {
"tileBaseUrl": "https://.../tiles/",
"zoom": 15,
"tileSize": 256
},
"viewport": {
"width": 800,
"height": 450,
"minLon": 117.0000,
"minLat": 36.6000,
"maxLon": 117.0800,
"maxLat": 36.6600
},
"variants": [
{
"variantId": "variant_a",
"name": "A线",
"routeCode": "route-variant-a",
"controls": [
{ "id": "start", "kind": "start", "lon": 117.01, "lat": 36.61 },
{ "id": "c1", "kind": "control", "lon": 117.02, "lat": 36.615 },
{ "id": "finish", "kind": "finish", "lon": 117.03, "lat": 36.62 }
],
"legs": [
{ "from": "start", "to": "c1" },
{ "from": "c1", "to": "finish" }
]
}
]
}
}
```
其中关键字段是：
- `baseTiles.tileBaseUrl`
- `baseTiles.zoom`
- `viewport.width / height`
- `viewport.minLon / minLat / maxLon / maxLat`
- `variants[].controls`
- `variants[].legs`
这些字段足够前端做只读预览。
---
## 6. 前端如何消费
前端准备页的消费方式建议如下：
### 6.1 底图渲染
- 使用低级别瓦片作为底图来源
- 按 `viewport` 与 `zoom` 计算需要的瓦片范围
- 只在准备页内绘制一张静态缩略底图
### 6.2 赛道叠加
- 根据 `viewport` 把控制点经纬度投影到预览图坐标
- 在 canvas 或同等绘制层上叠加：
- 起点
- 终点
- 控制点
- 腿线
### 6.3 多赛道切换
- 切换赛道时不重新换底图
- 只重绘叠加层
### 6.4 展示层级
准备页只做：
- 只读预览
- 不拖拽
- 不缩放
- 不交互打点
---
## 7. 多赛道场景如何处理
多赛道场景是这套方案的重点。
当前建议规则：
1. 同一活动下，所有 variant 共用一张底图
2. 当前选中的 variant 决定叠加层内容
3. 如果活动允许手动选赛道，切换赛道时预览同步切换
4. 如果活动是随机分配或后台指定：
- 准备页在最终绑定前可只显示地点底图
- 一旦后端返回最终绑定赛道，再显示该赛道 overlay
这套设计和当前多赛道 Variant 架构是一致的：
- 底图属于地图对象
- 叠加属于 variant 对象
---
## 8. 预览级别建议
建议预览能力分成 3 档：
### 8.1 `none`
- 不显示地图预览
- 只显示地点、地图、赛道文字信息
适用于：
- 不允许赛前预览的正式比赛
### 8.2 `summary`
- 显示底图
- 只显示简化赛道范围、起终点或大致区域
- 不暴露完整点位和腿线
适用于：
- 需要局前空间感，但不允许完整剧透路线
### 8.3 `full`
- 显示底图
- 显示完整点位与腿线
适用于：
- 体验活动
- 教学活动
- 低门槛公开活动
V1 建议先直接支持：
- `none`
- `full`
后面再补 `summary`。
---
## 9. 分阶段实施建议
### 9.1 V1
只做：
- 低级别瓦片底图
- 前端动态赛道叠加
- 支持多赛道切换联动
- 只读展示
不做：
- 复杂预览交互
- 预览模式细分
- 缩放与拖拽
### 9.2 V2
补：
- `none / summary / full`
- 不同活动类型的预览策略
- 更细的赛道保密规则
### 9.3 V3
考虑扩展到：
- 活动详情页缩略预览
- 活动列表卡片缩略图
- 赛后结果页路线回看缩略图
---
## 10. 不建议的方案
当前不建议：
### 10.1 单独制作一套预览地图资源
问题：
- 成本高
- 一致性差
- 发布链复杂
### 10.2 前端直接现场拼完整高精度瓦片地图
问题：
- 性能波动大
- 首次加载慢
- 多端一致性差
### 10.3 后端为每个 variant 预生成完整大图
问题：
- 多赛道下资源重复
- 每次改赛道都要重生图
- 扩展性不如“底图固定 + 叠加切换”
---
## 11. 当前建议结论
准备页地图预览最推荐的路线是：
**使用低级别正式瓦片作为预览底图，由前端在准备页动态叠加当前赛道。**
这条路线的优点是：
- 不新增独立地图资源
- 底图与正式地图同源
- 多赛道切换成本低
- 前后端职责清晰
- 易于分阶段落地
当前建议优先推进：
1. 后端补预览元数据最小字段
2. 前端在准备页实现只读底图 + overlay
3. 先支持 `full`
4. 后续再扩 `summary / none`

292
doc/gameplay/地图列表与默认体验活动方案.md Normal file
View File

@@ -0,0 +1,292 @@
# 地图列表与默认体验活动方案
> 文档版本：v1.0
> 最后更新：2026-04-07 14:35:00
本文档用于定义“地图列表”这条产品线如何与现有活动系统协同工作，重点解决以下问题：
- 是否需要独立的地图列表入口
- 默认体验活动如何挂在地图/地点下
- 默认体验活动是否必须出现在正式活动列表
- 后台应如何支持这套关系
本文档的核心原则是：
**地图列表是体验入口层，不是第二套业务内核。**
也就是说：
- 正式业务主链仍然是 `Event -> Release -> Launch -> Session`
- 地图列表只是帮助用户从“地点/地图”进入默认体验活动
---
## 1. 总体结论
建议增加一条独立的：
- `地图列表`
它主要面向：
- 未注册用户
- 想快速试玩的用户
- 先看地点/地图，再决定是否体验的用户
但这条线不应重新发明一套“体验配置系统”，而应继续复用现有：
- `Event`
- `EventRelease`
- `Launch`
- `Session`
默认体验活动只是：
- 一类特殊的 `Event`
- 可以挂在 `Place / MapAsset` 下
- 可以选择是否出现在正式活动列表
---
## 2. 基本对象关系
建议继续沿用当前对象模型：
- `Place`
- `MapAsset`
- `Event`
在此基础上，补一层关系：
- `defaultExperienceEvents[]`
可理解为：
- 一个地点下可有多张地图
- 一张地图下可挂 `0 ~ N` 个默认体验活动
默认体验活动本身不需要新建特殊业务对象，仍然是 `Event`。
---
## 3. 默认体验活动的定义
默认体验活动建议继续用 `Event` 承载，但补充两个活动级属性：
### 3.1 `isDefaultExperience`
- 类型：`boolean`
- 含义：该活动是否属于默认体验活动
### 3.2 `showInEventList`
- 类型：`boolean`
- 含义：该活动是否出现在正式活动列表中
这样就能支持以下场景：
1. 正式活动
- `isDefaultExperience = false`
- `showInEventList = true`
2. 纯地图体验活动
- `isDefaultExperience = true`
- `showInEventList = false`
3. 既是体验又允许出现在活动列表
- `isDefaultExperience = true`
- `showInEventList = true`
4. 当前不开放的体验活动
- 活动未 active
- 或未挂到地图
---
## 4. 产品入口建议
建议前台保留两条入口：
### 4.1 活动列表
面向正式活动。
默认只展示：
- `showInEventList = true`
不要求把所有默认体验活动都混进去。
### 4.2 地图列表
面向“先选地图/地点，再试玩”活动。
流程建议：
1. 首页进入 `地图列表`
2. 用户看到地点/地图卡片
3. 点进地图详情
4. 查看该地图下挂的默认体验活动
5. 点某个体验活动进入现有：
- 活动详情页
- 准备页
- 地图页
也就是说：
**地图列表负责入口分发，活动主链仍复用现有链路。**
---
## 5. 地图列表页建议
地图列表页第一阶段建议尽量简单。
### 每张地图卡片最小字段
- 地点名称
- 地图名称
- 地图预览图
- 简短描述
- 是否存在默认体验活动
- 默认体验数量
### 当前不必一开始就做
- 复杂筛选
- 复杂排序
- 地图标签系统
- 地图收藏
---
## 6. 地图详情页建议
地图详情页建议承担：
- 地图介绍
- 地图预览
- 默认体验活动列表
### 默认体验活动列表显示建议
每条体验活动可显示：
- 标题
- 副标题
- 玩法类型
- 当前状态
- 进入体验 CTA
如果该地图当前没有默认体验活动，应明确显示：
- `当前暂无体验活动`
不要整块隐藏。
---
## 7. 后台支持建议
后台后续应支持：
### 7.1 地图下挂体验活动
最少应支持：
- 一张地图可挂 `0 ~ N` 个默认体验活动
- 一个默认体验活动可绑定到某张地图
### 7.2 活动可见性控制
后台应能控制：
- 是否默认体验
- 是否出现在正式活动列表
也就是：
- `isDefaultExperience`
- `showInEventList`
### 7.3 不要求每种玩法都挂默认体验
后台不应把“默认体验活动”做成强制项。
可以是：
- 不挂
- 只挂顺序赛
- 只挂积分赛
- 顺序赛 + 积分赛都挂
这应由地图、运营目标和活动阶段决定，而不是系统硬约束。
---
## 8. 与现有活动系统的关系
这套方案必须继续遵守：
- 默认体验活动仍然是 `Event`
- 仍然要有 `EventRelease`
- 仍然通过 `play / launch / session` 进入
- 仍然遵守 `canLaunch`
不要为地图体验活动单独发明：
- 新的 launch 入口
- 新的 session 类型
- 新的结果体系
否则会把主链拆坏。
---
## 9. 推荐实施顺序
建议按以下顺序推进：
### 第一步
先把后台和对象关系定好：
- 地图可挂默认体验活动
- 活动可配置是否在活动列表出现
### 第二步
前台做：
- 地图列表页
- 地图详情页
### 第三步
地图详情页里的默认体验活动继续复用现有：
- 活动详情页
- 准备页
- 地图页
### 第四步
再决定是否补：
- 地图筛选
- 推荐体验
- 地图封面优化
---
## 10. 一句话结论
建议增加地图列表，但它应被定义为：
**默认体验活动的入口层，而不是第二套活动系统。**
后台后续只需支持：
- 地图下挂默认体验活动
- 默认体验活动是否出现在正式活动列表
这样既能支持未注册/试玩用户体验，也不会把现有活动主链拆成两套。

34
doc/gameplay/多线程联调协作方式.md
View File

@@ -1,15 +1,16 @@
# 多线程联调协作方式
> 文档版本：v1.1
> 最后更新：2026-04-03 11:15:00
> 文档版本：v1.2
> 最后更新：2026-04-07 10:32:36
## 目标
当前项目已经进入前后端联调阶段，并且存在多条并行工作线程：
当前项目已经进入前后端联调和多产品线并行阶段，并且存在多条并行工作线程：
- 前端线程
- 后端线程
- 总控线程
- 网站线程
这份文档用于明确三条线程如何协作、各自负责什么，以及如何通过共享文档同步事实，而不是靠口头记忆维持项目状态。
@@ -21,25 +22,28 @@
- 一个代码仓库
- 多条并行线程
- 四份根目录协作文档
- 六份根目录协作文档
- 一名全局维护者负责总览和收口
对应关系：
- 前端线程：推进小程序页面、状态链、模拟器接入、地图与体验层
- 后端线程：推进接口、配置发布、会话生命周期、业务数据模型
- 网站线程：推进官网、活动门户、地图体验入口、商务转化站重构
- 总控线程：负责全局判断、主线推进、交叉影响评估、文档索引与阶段总结
---
## 2. 当前协作文档的职责
当前跨线程沟通主线改为 4 份文件：
当前跨线程沟通主线改为 6 份文件：
- [t2b.md](D:/dev/cmr-mini/t2b.md)
- [b2t.md](D:/dev/cmr-mini/b2t.md)
- [t2f.md](D:/dev/cmr-mini/t2f.md)
- [f2t.md](D:/dev/cmr-mini/f2t.md)
- [t2w.md](D:/dev/cmr-mini/t2w.md)
- [w2t.md](D:/dev/cmr-mini/w2t.md)
旧的：
@@ -80,6 +84,22 @@
- 前端在哪些地方受阻
- 需要总控或后端确认什么
### 2.5 `t2w.md`
由总控线程维护，写给网站线程，用于记录：
- 当前阶段网站重构应推进什么
- 当前优先级是什么
- 哪些页面和转化链先做
### 2.6 `w2t.md`
由网站线程维护，写给总控线程，用于记录：
- 网站线程当前已完成什么
- 网站重构当前阻塞什么
- 需要总控确认什么
---
## 2.5 当前固定模板
@@ -128,6 +148,8 @@
- [b2t.md](D:/dev/cmr-mini/b2t.md)
- [t2f.md](D:/dev/cmr-mini/t2f.md)
- [f2t.md](D:/dev/cmr-mini/f2t.md)
- [t2w.md](D:/dev/cmr-mini/t2w.md)
- [w2t.md](D:/dev/cmr-mini/w2t.md)
以及当前代码事实：
@@ -203,6 +225,8 @@
- [b2t.md](D:/dev/cmr-mini/b2t.md)
- [t2f.md](D:/dev/cmr-mini/t2f.md)
- [f2t.md](D:/dev/cmr-mini/f2t.md)
- [t2w.md](D:/dev/cmr-mini/t2w.md)
- [w2t.md](D:/dev/cmr-mini/w2t.md)
特点：

46
doc/gameplay/联调架构阶段总结.md
View File

@@ -1,6 +1,6 @@
# 联调架构阶段总结
> 文档版本：v1.0
> 最后更新：2026-04-03 16:59:19
> 文档版本：v1.1
> 最后更新：2026-04-07 22:38:00
## 1. 当前结论
@@ -141,31 +141,53 @@ frontend 当前已配合提供：
### 6.2 正在推进
- 真实输入替换
- 更接近生产的联调环境
- 活动系统最小成品闭环回归
- 地图体验链第一刀回归
- 游客体验链第一刀回归
### 6.3 暂不启动
### 6.3 已进入当前最小成品闭环范围
- 活动卡片（列表）产品化
- 新玩家侧页面扩张
- 更复杂后台运营功能
- 活动卡片列表最小产品化第一刀
- 地图体验第一刀
- 游客模式第一刀
- 准备页地图预览 V1
### 6.4 当前后端收口原则
- backend 第一阶段活动模型先按：
- 单地图
- 单路线组
- 单玩法
收口推进
- 复杂多地图 / 多路线组 / 多玩法活动，后续通过：
- 活动实例化
- 组合入口层
- 组合卡片层
解决
---
## 7. 下一步建议
当前下一步不再是继续搭骨架，而是继续把真实输入往活动层推进。
当前下一步不再是继续搭骨架，而是把已经接通的玩家链真正收顺，并继续保持联调环境接近生产。
优先顺序建议：
1. `content manifest`
2. `presentation schema`
3. 活动文案样例
1. 活动列表第一刀联调回归与小修
2. 活动详情页 / 准备页去工程味
3. 地图体验链 / 游客体验链整链回归
4. 继续使用：
- `Bootstrap Demo`
- `一键补齐 Runtime 并发布`
- `一键标准回归`
做统一验证
同时继续保持：
- 前端只做联调回归和小修
- 前端不扩第二刀产品化
- 后端继续保证一键回归链稳定
- 后端按单地图 / 单路线组 / 单玩法先收模型
- 排障优先看：
- `回归结果汇总`
- `当前 Launch 实际配置摘要`

156
doc/gameplay/运维后台第一期方案.md Normal file
View File

@@ -0,0 +1,156 @@
# 运维后台第一期方案
> 文档版本：v1.0
> 最后更新：2026-04-07 10:24:38
本文档用于定义运维后台第一期的角色边界、模块范围和与当前 `/dev/workbench` 的分工，作为下周启动正式运维后台时的最小基线。
---
## 1. 目标
运维后台第一期的目标不是替代开发联调台，而是为非开发角色提供一套**可管理活动、可绑定资源、可发布版本**的最小后台。
第一期要解决的核心问题：
1. 运维人员可以查看和管理活动
2. 运维人员可以绑定展示定义、内容包和运行绑定
3. 运维人员可以发布和查看当前生效版本
4. 默认活动和自定义活动都能统一进入发布流
---
## 2. 与 workbench 的分工
### 2.1 workbench
继续保留为：
- 开发联调台
- 一键测试台
- 诊断台
- 回归台
继续负责：
- `Bootstrap Demo`
- 一键补齐 Runtime 并发布
- 一键标准回归
- Launch 实际配置摘要
- 前端调试日志
### 2.2 运维后台
第一期定位为：
- 运营配置台
- 发布管理台
- 非开发人员日常使用后台
不承担：
- 一键测试
- 分步诊断
- 调试日志查看
- 开发期 demo 数据准备
---
## 3. 第一期开哪些模块
### 3.1 活动管理
最小能力：
- 活动列表
- 活动详情
- 活动状态查看
- 默认体验活动标记查看
### 3.2 展示管理
最小能力：
- 查看 `EventPresentation`
- 绑定到活动
- 查看当前 active presentation
### 3.3 内容包管理
最小能力：
- 查看 `ContentBundle`
- 导入内容包摘要
- 绑定到活动
- 查看当前 active bundle
### 3.4 运行绑定管理
最小能力：
- 查看 `MapRuntimeBinding`
- 选择活动当前使用的 runtime binding
- 查看绑定摘要：
- `place`
- `map`
- `tile release`
- `course variant`
### 3.5 发布管理
最小能力：
- 发布当前活动
- 查看当前 release
- 查看历史 release
- 查看当前 release 绑定的：
- `presentation`
- `contentBundle`
- `runtime`
---
## 4. 第一阶段明确不做
第一期不做：
- 完整资源素材平台
- 复杂审核流
- 批量操作
- 回滚自动化
- 复杂权限模型
- 活动搭建器可视化编辑器
- 工作流编排
---
## 5. 页面建议
建议第一期后台至少包含这几页：
1. 活动列表页
2. 活动详情页
3. 展示定义选择页/弹层
4. 内容包选择页/弹层
5. 运行绑定选择页/弹层
6. 发布详情页
---
## 6. 启动时机
当前建议的时机是：
- 本周先完成“活动系统最小成品闭环”
- 下周开始做“运维后台第一期”
原因：
- 当前 workbench 仍承担联调标准化和回归职责
- 活动配置、发布、进入、结果回看这一条产品链还在本周收口
- 正式运维后台应在业务主链稳定后启动，避免两条后台线互相干扰
---
## 7. 一句话结论
运维后台第一期应作为**运营配置与发布后台**启动，不替代 workbench，不承担开发诊断；建议在本周活动系统最小成品闭环完成后，于下周正式开工。