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-03-30 18:49:22 +08:00
parent 3b9117427e
commit 24bc60bc7f
49 changed files with 462 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

407
doc/config/后台配置管理方案V2.md Normal file
View File

@@ -0,0 +1,407 @@
# 配置频繁变更场景下的后台管理方案
本文用于整理一套更适合“配置项变化很频繁”的后台方案。
适用前提：
- 配置驱动型应用
- 游戏规则和字段会持续变化
- PostgreSQL 作为主数据库
- Go 作为中间层
- 客户端最终读取静态 JSON
核心目标是：
**在保证后端稳定的前提下，让前端和玩法配置可以持续快速迭代。**
---
## 1. 核心原则
这版方案的核心思想只有一句：
**后端管理“容器、版本、引用、发布”，不要深度管理每个细字段。**
也就是说：
- 后端负责管理对象关系
- 后端负责管理版本和发布
- 后端负责做基础校验
- 后端尽量不要写死每个玩法里的所有字段细节
---
## 2. 总体结构
推荐分成 3 层：
### 2.1 编辑层
后台管理系统面向的是“对象”，不是最终运行文件。
建议核心对象仍然是：
- `Map`
- `Playfield`
- `GameMode`
- `ResourcePack`
- `Event`
### 2.2 装配层
Go 中间层负责：
- 读取对象
- 合并引用
- 基础校验
- 生成最终运行态配置
### 2.3 发布层
装配完成后，生成静态 JSON 上传到 OSS/CDN。
客户端只读取：
- 已发布的静态配置
---
## 3. 数据库存什么
数据库建议只存两类数据：
### 3.1 稳定元信息
结构化列保存：
- `id`
- `slug`
- `name`
- `status`
- `current_version_id`
- `created_at`
- `updated_at`
### 3.2 易变配置内容
使用 `jsonb` 保存：
- `content_jsonb`
也就是说，每个对象都建议拆成：
- 主表
- version 表
例如：
- `maps` / `map_versions`
- `playfields` / `playfield_versions`
- `game_modes` / `game_mode_versions`
- `resource_packs` / `resource_pack_versions`
- `events` / `event_versions`
这套结构最适合承接频繁变化的配置字段。
---
## 4. 为什么要用 version 表
配置频繁变化时，版本表非常重要：
- 支持草稿
- 支持当前版
- 支持发布版
- 支持历史回滚
- 支持 diff
- 支持审计
如果没有版本表，配置演进到后面会越来越难控。
---
## 5. 后端真正该负责的内容
后端建议强管理下面这 4 件事：
### 5.1 对象关系
例如：
- Event 引用哪个 Map
- Event 引用哪个 Playfield
- Event 引用哪个 GameMode
- Event 引用哪个 ResourcePack
### 5.2 版本机制
例如：
- 草稿
- 当前版本
- 发布版本
- 回滚历史
### 5.3 基础校验
只做真正稳定的校验：
- 顶层结构是否合法
- 引用是否存在
- schemaVersion 是否兼容
- 必填对象是否齐全
### 5.4 发布装配
把编辑态对象装配成最终运行态 JSON。
---
## 6. 后端不要过度负责的内容
后端不要把下面这些写死：
- 每个玩法的小规则字段
- 每个 HUD 开关
- 每个实验性参数
- 每个视觉细节配置
- 每次快速迭代里新增的小配置项
这些变化太频繁，应该优先放在 `jsonb` 内容里，由前端消费。
一句话：
**后端不要成为“所有细字段的业务解释器”。**
---
## 7. 配置校验的推荐分层
建议分成 3 层校验。
### 7.1 通用结构校验
所有配置都校验：
- `schemaVersion`
- `map`
- `playfield`
- `game`
### 7.2 公共字段校验
只校验稳定公共字段，例如：
- `game.mode` 必须存在
- `game.punch.radiusMeters > 0`
### 7.3 玩法校验器
按 `game.mode` 分发，例如：
- `classic-sequential` validator
- `score-o` validator
但这里有个重要原则：
**未识别字段默认允许透传。**
也就是说：
- 不要因为多了一个新字段就发布失败
- 只有破坏基础结构或关键规则时才拦截
---
## 8. 后台编辑策略
后台不要追求“一开始把所有字段都做成完美表单”。
建议分成两类：
### 8.1 稳定字段
做正式表单：
- 名称
- 状态
- 模式
- 地图引用
- Playfield 引用
- 资源包引用
- 关键半径
- 是否必须起点/终点
### 8.2 易变字段
先保留模块化 JSON 编辑区：
- `game.sequence`
- `game.guidance`
- `game.visibility`
- `game.feedback`
- `playfield.controlOverrides`
- 其他试验性字段
等这些字段稳定后，再逐步升级成正式表单。
这会比一开始硬做全表单更现实。
---
## 9. 推荐的发布模型
建议增加一层：
- `event_releases`
推荐字段：
- `id`
- `event_id`
- `event_version_id`
- `release_no`
- `manifest_url`
- `published_by`
- `published_at`
- `status`
发布流程：
1. 后台选择某个 `event_version`
2. Go 层装配最终配置
3. Go 层校验
4. 上传 OSS/CDN
5. 写入 release 记录
客户端只消费：
- 某次 release 对应的静态 JSON
---
## 10. Go 中间层的职责
Go 中间层建议承担 4 类职责：
### 10.1 装配器
负责把：
- `Map`
- `Playfield`
- `GameMode`
- `ResourcePack`
- `Event Overrides`
装配成最终运行态配置。
### 10.2 校验器
负责：
- 通用校验
- 公共字段校验
- 按玩法分发的插件式校验
### 10.3 发布器
负责：
- 生成静态 JSON
- 上传 OSS/CDN
- 写入 release
### 10.4 预览 / Diff
负责：
- 给后台看发布前的预览
- 对比不同版本差异
一句话：
**Go 中间层本质上是配置编译器，不只是 CRUD 服务。**
---
## 11. 这套方案为什么适合当前项目
因为当前项目的真实情况就是：
- 配置字段变化快
- 玩法在持续演进
- 前端经常需要新增规则项
- 客户端更适合消费静态配置
如果后端每次都跟着细字段改表、改结构、改接口，成本会非常高。
这套方案可以避免：
- 频繁 migration
- 后端字段爆炸
- 每次小字段变更都改很多 Go 代码
---
## 12. 推荐你现在就定死的原则
### 原则 1
**数据库结构稳定，配置内容灵活。**
### 原则 2
**后端强管理对象关系，不强管理每个细字段。**
### 原则 3
**未知字段默认允许透传。**
### 原则 4
**客户端消费细规则，后端负责发布与校验。**
### 原则 5
**最终运行态永远是静态 JSON。**
---
## 13. 和当前目录结构的关系
如果当前静态目录是：
- `map/`
- `kml/`
- `event/`
这套可以继续保留。
理解方式是：
- 数据库 = 编辑态
- Go 装配 = 发布态转换
- OSS 目录 = 运行态产物
也就是说后台发布后，继续生成：
- `event/classic-sequential.json`
- `event/score-o.json`
- `map/...`
- `kml/...`
客户端现有读取逻辑无需推翻。
---
## 14. 推荐实施顺序
建议按下面顺序推进：
### 第一步
先建 5 个核心对象：
- `Map`
- `Playfield`
- `GameMode`
- `ResourcePack`
- `Event`
### 第二步
为每个对象补 version 表。
### 第三步
Go 中间层先做最小装配功能。
### 第四步
实现发布到 OSS/CDN。
### 第五步
后台逐步把稳定字段表单化。
### 第六步
把易变字段继续保留为 JSON 编辑区。
---
## 15. 一句话总结
这套更适合频繁变化配置项的后台方案是：
**PostgreSQL 存“版本化对象 + jsonb 内容”，Go 中间层做“装配 + 校验 + 发布”，客户端只读静态发布结果。**

651
doc/config/当前最全配置模板.md Normal file
View File

@@ -0,0 +1,651 @@
# 游戏配置全量模板（当前开发实现版）
本文档提供一份 **截至当前开发状态，客户端已实现或已正式消费的较完整配置模板**。
目标：
- 给后端、后台、联调一份“当前最全可用模板”
- 帮助梳理哪些字段已经生效
- 后续新增字段时，以这份模板持续补充
说明：
- 本模板优先以**当前客户端代码真实实现**为准
- 不是未来终态，只代表“当前这一版已经能消费的字段”
- 以顺序赛为主模板，同时说明积分赛差异点
---
## 1. 当前最全模板
```json
{
"schemaVersion": "1",
"version": "2026.03.30",
"app": {
"id": "sample-full-001",
"title": "完整配置示例",
"locale": "zh-CN"
},
"map": {
"tiles": "../map/lxcb-001/tiles/",
"mapmeta": "../map/lxcb-001/tiles/meta.json",
"declination": 6.91,
"initialView": {
"zoom": 17
}
},
"playfield": {
"kind": "course",
"source": {
"type": "kml",
"url": "../kml/lxcb-001/10/c01.kml"
},
"CPRadius": 6,
"metadata": {
"title": "完整路线示例",
"code": "full-001"
},
"controlOverrides": {
"start-1": {
"template": "focus",
"title": "比赛开始",
"body": "从这里触发，先熟悉地图方向。",
"clickTitle": "起点说明",
"clickBody": "点击起点可再次查看起跑说明。",
"autoPopup": true,
"once": true,
"priority": 1,
"contentExperience": {
"type": "h5",
"url": "https://example.com/content/start-1",
"bridge": "content-v1",
"presentation": "dialog"
},
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/start-1-click",
"bridge": "content-v1",
"presentation": "dialog"
}
},
"control-1": {
"template": "story",
"score": 10,
"title": "第一检查点",
"body": "完成该点后继续推进。",
"clickTitle": "第一检查点",
"clickBody": "点击查看该点的补充说明。",
"autoPopup": true,
"once": false,
"priority": 1,
"contentExperience": {
"type": "h5",
"url": "https://example.com/content/control-1",
"bridge": "content-v1",
"presentation": "dialog"
},
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/control-1-click",
"bridge": "content-v1",
"presentation": "dialog"
}
},
"control-2": {
"template": "minimal",
"title": "第二检查点",
"body": "这个点配置成手动查看内容。",
"clickTitle": "第二检查点",
"clickBody": "点击查看手动内容。",
"autoPopup": false,
"once": true,
"priority": 1
},
"finish-1": {
"template": "focus",
"title": "比赛结束",
"body": "恭喜完成本次路线。",
"clickTitle": "终点说明",
"clickBody": "点击终点可再次查看结束说明。",
"autoPopup": true,
"once": true,
"priority": 2,
"clickExperience": {
"type": "h5",
"url": "https://example.com/content/finish-1-click",
"bridge": "content-v1",
"presentation": "dialog"
}
}
}
},
"game": {
"mode": "classic-sequential",
"rulesVersion": "1",
"session": {
"startManually": true,
"requiresStartPunch": true,
"requiresFinishPunch": true,
"autoFinishOnLastControl": false,
"maxDurationSec": 5400
},
"punch": {
"policy": "enter-confirm",
"radiusMeters": 5,
"requiresFocusSelection": false
},
"sequence": {
"skip": {
"enabled": true,
"radiusMeters": 30,
"requiresConfirm": true
}
},
"scoring": {
"type": "score",
"defaultControlScore": 10
},
"guidance": {
"showLegs": true,
"legAnimation": true,
"allowFocusSelection": false
},
"visibility": {
"revealFullPlayfieldAfterStartPunch": true
},
"finish": {
"finishControlAlwaysSelectable": false
},
"telemetry": {
"heartRate": {
"age": 30,
"restingHeartRateBpm": 62,
"userWeightKg": 65
}
},
"feedback": {
"audioProfile": "default",
"hapticsProfile": "default",
"uiEffectsProfile": "default"
}
},
"resources": {
"audioProfile": "default",
"contentProfile": "default",
"themeProfile": "default-race"
},
"debug": {
"allowModeSwitch": false,
"allowMockInput": false,
"allowSimulator": false
}
}
```
---
## 2. 顶层字段说明
### `schemaVersion`
- 类型：`string`
- 必填：是
- 说明：配置结构版本
- 当前建议值：`"1"`
### `version`
- 类型：`string`
- 必填：是
- 说明：配置内容版本号
### `app`
- 类型：`object`
- 必填：是
- 说明：活动级基础信息
### `map`
- 类型：`object`
- 必填：是
- 说明：地图底座信息
### `playfield`
- 类型：`object`
- 必填：是
- 说明：点位空间、内容覆盖、点位元信息
### `game`
- 类型：`object`
- 必填：是
- 说明：玩法规则与对局流程
### `resources`
- 类型：`object`
- 必填：否
- 说明：资源 profile 引用
### `debug`
- 类型：`object`
- 必填：否
- 说明：调试开关
---
## 3. `app` 字段说明
### `app.id`
- 类型：`string`
- 说明：活动配置 ID
### `app.title`
- 类型：`string`
- 说明：活动标题 / 比赛名称
### `app.locale`
- 类型：`string`
- 说明：语言环境
- 当前常用值：`zh-CN`
---
## 4. `map` 字段说明
### `map.tiles`
- 类型：`string`
- 必填：是
- 说明：瓦片根路径
### `map.mapmeta`
- 类型：`string`
- 必填：是
- 说明：地图 meta 文件路径
### `map.declination`
- 类型：`number`
- 必填：否
- 说明：磁偏角
- 影响：真北 / 磁北换算
### `map.initialView.zoom`
- 类型：`number`
- 必填：否
- 说明：初始缩放级别
- 建议默认值：`17`
---
## 5. `playfield` 字段说明
### `playfield.kind`
- 类型：`string`
- 说明：空间对象类型
- 当前常用值：
- `course`
- `control-set`
### `playfield.source.type`
- 类型：`string`
- 说明：空间来源类型
- 当前推荐值：`kml`
### `playfield.source.url`
- 类型：`string`
- 说明：KML 路径
### `playfield.CPRadius`
- 类型：`number`
- 说明：检查点绘制半径
- 建议默认值：`6`
### `playfield.metadata.title`
- 类型：`string`
- 说明：路线标题
### `playfield.metadata.code`
- 类型：`string`
- 说明：路线编码
---
## 6. `playfield.controlOverrides` 字段说明
### key 命名规则
- 起点：`start-1`
- 普通点：`control-1`、`control-2`、`control-3`
- 终点：`finish-1`
### 当前支持字段
#### `template`
- 类型：`string`
- 说明：原生内容卡模板
- 当前支持：
- `minimal`
- `story`
- `focus`
#### `score`
- 类型：`number`
- 说明：积分赛点位分值
#### `title`
- 类型：`string`
- 说明：打点完成后自动弹出的标题
#### `body`
- 类型：`string`
- 说明：打点完成后自动弹出的正文
#### `clickTitle`
- 类型：`string`
- 说明：点击点位时弹出的标题
- 默认逻辑：未配置时回退到 `title`
#### `clickBody`
- 类型：`string`
- 说明：点击点位时弹出的正文
- 默认逻辑：未配置时回退到 `body`
#### `autoPopup`
- 类型：`boolean`
- 说明：打点完成后是否自动弹出
- 默认逻辑：`true`
- 特殊逻辑：`game.punch.policy = "enter"` 时不自动弹原生内容
#### `once`
- 类型：`boolean`
- 说明：本局只展示一次
- 默认逻辑：`false`
#### `priority`
- 类型：`number`
- 说明：内容优先级，越大越高
- 默认逻辑：
- 普通点：`1`
- 终点：`2`
#### `contentExperience`
- 类型：`object`
- 说明：打点完成后的 H5 详情/互动扩展配置
- 注意：当前不是直接顶替原生弹窗，而是通过原生卡片 CTA 进入
#### `contentExperience.type`
- 类型：`string`
- 说明：内容扩展承载类型
- 当前支持：
- `native`
- `h5`
#### `contentExperience.url`
- 类型：`string`
- 说明：H5 详情页地址
#### `contentExperience.bridge`
- 类型：`string`
- 说明：Bridge 协议版本
- 当前推荐值：`content-v1`
#### `contentExperience.presentation`
- 类型：`string`
- 说明：H5 内容页展示形态
- 当前支持值：
- `dialog`
- `fullscreen`
#### `clickExperience`
- 类型：`object`
- 说明：点击点位时的 H5 详情/互动扩展配置
- 规则同 `contentExperience`
---
## 7. `game` 字段说明
### `game.mode`
- 类型：`string`
- 说明：玩法模式
- 当前常用值：
- `classic-sequential`
- `score-o`
### `game.rulesVersion`
- 类型：`string`
- 说明：规则版本号
### `game.session.startManually`
- 类型：`boolean`
- 说明：是否手动开始
### `game.session.requiresStartPunch`
- 类型：`boolean`
- 说明：是否必须打起点
### `game.session.requiresFinishPunch`
- 类型：`boolean`
- 说明：是否必须打终点
### `game.session.autoFinishOnLastControl`
- 类型：`boolean`
- 说明：最后一个目标完成后是否自动结束
### `game.session.maxDurationSec`
- 类型：`number`
- 说明：最大对局时长，单位秒
### `game.punch.policy`
- 类型：`string`
- 说明：打点策略
- 当前常用值：
- `enter-confirm`
- `enter`
### `game.punch.radiusMeters`
- 类型：`number`
- 说明：打点半径，单位米
### `game.punch.requiresFocusSelection`
- 类型：`boolean`
- 说明：是否需要先聚焦/选中目标再打点
### `game.sequence.skip.enabled`
- 类型：`boolean`
- 说明：顺序赛是否允许跳点
### `game.sequence.skip.radiusMeters`
- 类型：`number`
- 说明：跳点可用半径
### `game.sequence.skip.requiresConfirm`
- 类型：`boolean`
- 说明：跳点是否需要二次确认
### `game.scoring.type`
- 类型：`string`
- 说明：积分模式类型
- 当前常用值：`score`
### `game.scoring.defaultControlScore`
- 类型：`number`
- 说明：默认控制点分值
### `game.guidance.showLegs`
- 类型：`boolean`
- 说明：是否显示路线腿段
### `game.guidance.legAnimation`
- 类型：`boolean`
- 说明：是否开启路线腿段动画
### `game.guidance.allowFocusSelection`
- 类型：`boolean`
- 说明：是否允许点击点位选中目标
### `game.visibility.revealFullPlayfieldAfterStartPunch`
- 类型：`boolean`
- 说明：打完起点后是否显示完整场地
### `game.finish.finishControlAlwaysSelectable`
- 类型：`boolean`
- 说明：终点是否始终可选
### `game.telemetry.heartRate.age`
- 类型：`number`
- 说明：用户年龄
### `game.telemetry.heartRate.restingHeartRateBpm`
- 类型：`number`
- 说明：静息心率
### `game.telemetry.heartRate.userWeightKg`
- 类型：`number`
- 说明：体重，单位公斤
### `game.feedback.audioProfile`
- 类型：`string`
- 说明：音效 profile
### `game.feedback.hapticsProfile`
- 类型：`string`
- 说明：震动 profile
### `game.feedback.uiEffectsProfile`
- 类型：`string`
- 说明：UI 动效 profile
---
## 8. `resources` 字段说明
### `resources.audioProfile`
- 类型：`string`
- 说明：资源音效配置档
### `resources.contentProfile`
- 类型：`string`
- 说明：内容资源配置档
### `resources.themeProfile`
- 类型：`string`
- 说明：主题配置档
---
## 9. `debug` 字段说明
### `debug.allowModeSwitch`
- 类型：`boolean`
- 说明：是否允许玩法切换调试
### `debug.allowMockInput`
- 类型：`boolean`
- 说明：是否允许模拟输入
### `debug.allowSimulator`
- 类型：`boolean`
- 说明：是否允许模拟器调试
---
## 10. 积分赛差异点
如果使用积分赛，通常要修改这几项：
```json
{
"playfield": {
"kind": "control-set"
},
"game": {
"mode": "score-o",
"guidance": {
"showLegs": false,
"legAnimation": false,
"allowFocusSelection": true
},
"finish": {
"finishControlAlwaysSelectable": true
}
}
}
```
并在 `playfield.controlOverrides` 中为普通点补：
- `score`
---
## 11. 推荐配套阅读
- [D:\dev\cmr-mini\doc\config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
- [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
- [D:\dev\cmr-mini\doc\config-docs-index.md](D:/dev/cmr-mini/doc/config/配置文档索引.md)

202
doc/config/最小游戏配置模板.md Normal file
View File

@@ -0,0 +1,202 @@
# 游戏最小可跑配置模板
本文档提供一份 **去掉大部分选配项之后，当前客户端可以直接跑起来的最小配置模板**。
目标：
- 给联调、后台、快速起新活动一个最小起步模板
- 保证只填最必要字段时，也能正常进入地图、开始比赛、完成流程
- 每个字段都带简要说明，方便直接照着改
说明：
- 本模板优先保证“能跑”
- 默认以**顺序赛**作为最小示例
- 如果要做积分赛，只需要替换少量字段
---
## 1. 最小模板
```json
{
"schemaVersion": "1",
"version": "2026.03.30",
"app": {
"id": "sample-minimal-001",
"title": "最小顺序赛示例"
},
"map": {
"tiles": "../map/lxcb-001/tiles/",
"mapmeta": "../map/lxcb-001/tiles/meta.json"
},
"playfield": {
"kind": "course",
"source": {
"type": "kml",
"url": "../kml/lxcb-001/10/c01.kml"
}
},
"game": {
"mode": "classic-sequential",
"punch": {
"policy": "enter-confirm",
"radiusMeters": 5
}
}
}
```
---
## 2. 字段说明
### `schemaVersion`
- 类型：`string`
- 必填：是
- 说明：配置结构版本
- 当前建议值：`"1"`
### `version`
- 类型：`string`
- 必填：是
- 说明：配置版本号
- 建议写法：日期或发布号，例如 `2026.03.30`
### `app.id`
- 类型：`string`
- 必填：是
- 说明：活动配置实例 ID
- 用途：区分不同活动或不同配置版本
### `app.title`
- 类型：`string`
- 必填：是
- 说明：活动标题 / 比赛名称
### `map.tiles`
- 类型：`string`
- 必填：是
- 说明：地图瓦片根路径
### `map.mapmeta`
- 类型：`string`
- 必填：是
- 说明：地图 meta 文件路径
### `playfield.kind`
- 类型：`string`
- 必填：是
- 说明：空间对象类型
- 最小顺序赛推荐值：`course`
- 最小积分赛推荐值：`control-set`
### `playfield.source.type`
- 类型：`string`
- 必填：是
- 说明：空间底稿来源类型
- 当前推荐值：`kml`
### `playfield.source.url`
- 类型：`string`
- 必填：是
- 说明：KML 文件路径
### `game.mode`
- 类型：`string`
- 必填：是
- 说明：玩法模式
- 当前常用值：
- `classic-sequential`
- `score-o`
### `game.punch.policy`
- 类型：`string`
- 必填：是
- 说明：打点触发方式
- 当前常用值：
- `enter-confirm`
- `enter`
### `game.punch.radiusMeters`
- 类型：`number`
- 必填：是
- 说明：打点判定半径，单位米
- 建议默认值：`5`
---
## 3. 最小积分赛改法
如果你要把这份最小模板改成积分赛，只需要改这几项：
```json
{
"playfield": {
"kind": "control-set",
"source": {
"type": "kml",
"url": "../kml/lxcb-001/10/c01.kml"
}
},
"game": {
"mode": "score-o",
"punch": {
"policy": "enter-confirm",
"radiusMeters": 5
}
}
}
```
---
## 4. 当前最小模板默认逻辑
即使你没有填写下面这些字段，当前客户端也会按默认逻辑运行：
- `map.declination`
- 默认按 `0` 处理
- `map.initialView.zoom`
- 默认由客户端初始视口逻辑接管
- `playfield.CPRadius`
- 默认按客户端内置值处理
- `game.session.*`
- 使用玩法默认逻辑
- `game.guidance.*`
- 使用当前默认引导逻辑
- `game.visibility.*`
- 使用当前默认可见性逻辑
- `resources.*`
- 使用默认资源 profile
- `debug.*`
- 默认关闭
---
## 5. 适用场景
这份模板适合：
- 新活动快速起盘
- 联调验证地图和 KML 是否正常
- 后台先跑通配置装配链
- 调试客户端主流程是否可进入
如果要做正式项目，请继续参考：
- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
- [D:\dev\cmr-mini\doc\config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)

200
doc/config/积分赛最小配置模板.md Normal file
View File

@@ -0,0 +1,200 @@
# 积分赛最小配置模板
本文档提供一份 **积分赛（`score-o`）最小可跑配置模板**。
目标：
- 只保留积分赛跑通所需的最少字段
- 适合快速起活动、联调、排查配置链
- 每个字段都带简要说明
---
## 1. 最小模板
```json
{
"schemaVersion": "1",
"version": "2026.03.30",
"app": {
"id": "sample-score-o-minimal-001",
"title": "积分赛最小示例"
},
"map": {
"tiles": "../map/lxcb-001/tiles/",
"mapmeta": "../map/lxcb-001/tiles/meta.json"
},
"playfield": {
"kind": "control-set",
"source": {
"type": "kml",
"url": "../kml/lxcb-001/10/c01.kml"
}
},
"game": {
"mode": "score-o",
"punch": {
"policy": "enter-confirm",
"radiusMeters": 5
}
}
}
```
---
## 2. 字段说明
### `schemaVersion`
- 类型：`string`
- 必填：是
- 说明：配置结构版本
- 当前建议值：`"1"`
### `version`
- 类型：`string`
- 必填：是
- 说明：配置版本号
### `app.id`
- 类型：`string`
- 必填：是
- 说明：活动配置实例 ID
### `app.title`
- 类型：`string`
- 必填：是
- 说明：活动标题 / 比赛名称
### `map.tiles`
- 类型：`string`
- 必填：是
- 说明：地图瓦片根路径
### `map.mapmeta`
- 类型：`string`
- 必填：是
- 说明：地图 meta 文件路径
### `playfield.kind`
- 类型：`string`
- 必填：是
- 说明：空间对象类型
- 积分赛固定使用：`control-set`
### `playfield.source.type`
- 类型：`string`
- 必填：是
- 说明：空间底稿来源类型
- 当前推荐值：`kml`
### `playfield.source.url`
- 类型：`string`
- 必填：是
- 说明：KML 文件路径
### `game.mode`
- 类型：`string`
- 必填：是
- 说明：玩法模式
- 积分赛固定值：`score-o`
### `game.punch.policy`
- 类型：`string`
- 必填：是
- 说明：打点策略
- 当前常用值：
- `enter-confirm`
- `enter`
### `game.punch.radiusMeters`
- 类型：`number`
- 必填：是
- 说明：打点判定半径，单位米
- 建议默认值：`5`
---
## 3. 当前默认逻辑
如果你不写下面这些字段，积分赛会按当前客户端默认逻辑运行：
- `map.declination`
- 默认按 `0` 处理
- `map.initialView.zoom`
- 默认由客户端初始视口逻辑接管
- `playfield.CPRadius`
- 默认按客户端内置值处理
- `playfield.controlOverrides.*.score`
- 没配时走 `game.scoring.defaultControlScore` 或玩法默认值
- `game.session.*`
- 默认手动开始
- `game.guidance.allowFocusSelection`
- 默认按积分赛逻辑允许选点
- `game.finish.finishControlAlwaysSelectable`
- 默认按积分赛逻辑处理终点可选
- `resources.*`
- 默认 profile
- `debug.*`
- 默认关闭
---
## 4. 推荐补充字段
如果你要让积分赛更接近正式活动，通常很快会补这几项：
```json
{
"playfield": {
"controlOverrides": {
"control-1": {
"score": 10
},
"control-2": {
"score": 20
}
}
},
"game": {
"scoring": {
"type": "score",
"defaultControlScore": 10
},
"guidance": {
"allowFocusSelection": true
},
"finish": {
"finishControlAlwaysSelectable": true
}
}
}
```
---
## 5. 适用场景
这份模板适合：
- 快速验证积分赛主流程
- 联调自由选点、积分累加、终点结束
- 后台先跑通最小积分赛配置
如果要看更完整版本，请继续参考：
- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
- [D:\dev\cmr-mini\event\score-o.json](D:/dev/cmr-mini/event/score-o.json)

220
doc/config/配置文档索引.md Normal file
View File

@@ -0,0 +1,220 @@
# 配置文档索引
本文档用于汇总当前项目所有与**配置设计、配置样例、配置管理**相关的文档，作为统一入口。
适用对象：
- 客户端开发
- 服务端开发
- 后台管理设计
- 配置录入与联调
---
## 1. 配置核心结构
当前项目的配置主入口已经稳定在：
```json
{
"schemaVersion": "1",
"version": "2026.03.30",
"app": {},
"map": {},
"playfield": {},
"game": {},
"resources": {},
"debug": {}
}
```
顶层职责建议固定为：
- `app`
活动级基础信息
- `map`
地图底图与空间底座
- `playfield`
当前玩法使用的空间对象定义
- `game`
当前玩法规则配置
- `resources`
资源包与 profile
- `debug`
调试与开发开关
当前推荐的核心原则：
- 配置只描述，不执行逻辑
- `KML` 描述空间事实，配置描述玩法解释
- `playfield` 是上位概念，`course` 只是其中一种 `kind`
- 当前阶段继续以单文件配置为主，后续再逐步升级成 manifest 组合
如果你需要看旧版长文讨论稿，已经移到归档：
- [config-design-proposal.md](/D:/dev/cmr-mini/doc/archive/config/配置设计方案.md)
---
## 2. 配置选项字典
### [config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
作用：
- 列出当前客户端已经支持或已预留的配置项
- 说明每个字段的类型、含义、默认逻辑
- 作为后续新增字段时的持续维护文档
适合阅读时机：
- 想知道某个字段是否已实现
- 想知道字段应该怎么写
- 想确认默认行为时
### [track-visualization-proposal.md](D:/dev/cmr-mini/doc/rendering/轨迹可视化方案.md)
作用：
- 说明 `none / full / tail` 三种轨迹模式
- 说明拖尾轨迹的默认策略与推荐参数
- 说明当前轨迹样式的配置结构
### [gps-marker-style-system-proposal.md](D:/dev/cmr-mini/doc/rendering/GPS点样式系统方案.md)
作用：
- 说明 GPS 点样式系统的目标分层
- 说明默认样式、朝向小三角和品牌 logo 扩展思路
- 说明第一阶段最小实现字段和长期演进方向
### [gps-marker-animation-system-proposal.md](D:/dev/cmr-mini/doc/rendering/GPS点动画系统方案.md)
作用：
- 说明 GPS 点动画系统的状态分层
- 说明 `idle / moving / fast-moving / warning` 的第一阶段实现思路
- 说明动画 profile、运行时内部字段和 `standard / lite` 降级策略
---
## 3. 当前推荐模板
### [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
作用：
- 提供“最小可跑”的游戏配置模板
- 去掉绝大部分选配项
- 适合快速起步、联调和排查配置链
### [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config/顺序赛最小配置模板.md)
作用：
- 提供顺序赛最小可跑模板
- 适合快速起顺序赛活动
### [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config/积分赛最小配置模板.md)
作用：
- 提供积分赛最小可跑模板
- 适合快速起积分赛活动
### [config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
作用：
- 提供“当前开发状态最全”的配置模板
- 汇总目前客户端已实现或已消费的主要字段
- 适合后端、后台和联调统一对齐
---
## 4. 运行中的样例配置
### [event/classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
作用：
- 当前顺序赛样例配置
- 可直接联调
- 已包含控制点内容覆盖示例
### [event/score-o.json](D:/dev/cmr-mini/event/score-o.json)
作用：
- 当前积分赛样例配置
- 可直接联调
- 已包含分值、起终点内容、点击内容示例
---
## 5. 后台与服务端配置管理方案
### [backend-config-management-v2.md](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)
作用：
- 在“配置项变化频繁”前提下重写的后台方案
- 更强调：
- 稳定骨架
- `jsonb`
- 版本
- 发布
- 透传未知字段
推荐优先看这一份。
---
## 6. 推荐阅读顺序
如果你是第一次接触这套配置体系，建议按这个顺序看：
1. 本页“配置核心结构”一节
2. [config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
3. [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
4. [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config/顺序赛最小配置模板.md)
5. [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config/积分赛最小配置模板.md)
6. [config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
7. [event/classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
8. [event/score-o.json](D:/dev/cmr-mini/event/score-o.json)
9. [backend-config-management-v2.md](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)
---
## 7. 维护约定
后续每次新增配置能力时，建议至少同步更新这几处：
1. [config-option-dictionary.md](D:/dev/cmr-mini/doc/config/配置选项字典.md)
2. [config-template-minimal-game.md](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
3. [config-template-minimal-classic-sequential.md](D:/dev/cmr-mini/doc/config/顺序赛最小配置模板.md)
4. [config-template-minimal-score-o.md](D:/dev/cmr-mini/doc/config/积分赛最小配置模板.md)
5. [config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
6. 对应玩法的 `event/*.json` 样例
7. 如果涉及顶层结构变化，先更新本页“配置核心结构”一节，再视情况补充归档讨论稿
这样可以保证：
- 文档
- 样例
- 代码
- 后台录入
保持一致。
---
## 8. 已归档文档
下列文档仍保留在归档目录，但不再作为当前主入口：
- [config-default-template.md](/D:/dev/cmr-mini/doc/archive/config/默认配置模板.md)
- [config-design-proposal.md](/D:/dev/cmr-mini/doc/archive/config/配置设计方案.md)
- [config-template-classic-sequential.md](/D:/dev/cmr-mini/doc/archive/config/顺序赛配置模板.md)
- [config-template-score-o.md](/D:/dev/cmr-mini/doc/archive/config/积分赛配置模板.md)
- [backend-config-management-proposal.md](/D:/dev/cmr-mini/doc/archive/config/后台配置管理方案.md)

1075
doc/config/配置选项字典.md Normal file
View File

File diff suppressed because it is too large Load Diff

165
doc/config/顺序赛最小配置模板.md Normal file
View File

@@ -0,0 +1,165 @@
# 顺序赛最小配置模板
本文档提供一份 **顺序赛（`classic-sequential`）最小可跑配置模板**。
目标：
- 只保留顺序赛跑通所需的最少字段
- 适合快速起活动、联调、排查配置链
- 每个字段都带简要说明
---
## 1. 最小模板
```json
{
"schemaVersion": "1",
"version": "2026.03.30",
"app": {
"id": "sample-classic-minimal-001",
"title": "顺序赛最小示例"
},
"map": {
"tiles": "../map/lxcb-001/tiles/",
"mapmeta": "../map/lxcb-001/tiles/meta.json"
},
"playfield": {
"kind": "course",
"source": {
"type": "kml",
"url": "../kml/lxcb-001/10/c01.kml"
}
},
"game": {
"mode": "classic-sequential",
"punch": {
"policy": "enter-confirm",
"radiusMeters": 5
}
}
}
```
---
## 2. 字段说明
### `schemaVersion`
- 类型：`string`
- 必填：是
- 说明：配置结构版本
- 当前建议值：`"1"`
### `version`
- 类型：`string`
- 必填：是
- 说明：配置版本号
### `app.id`
- 类型：`string`
- 必填：是
- 说明：活动配置实例 ID
### `app.title`
- 类型：`string`
- 必填：是
- 说明：活动标题 / 比赛名称
### `map.tiles`
- 类型：`string`
- 必填：是
- 说明：地图瓦片根路径
### `map.mapmeta`
- 类型：`string`
- 必填：是
- 说明：地图 meta 文件路径
### `playfield.kind`
- 类型：`string`
- 必填：是
- 说明：空间对象类型
- 顺序赛固定使用：`course`
### `playfield.source.type`
- 类型：`string`
- 必填：是
- 说明：空间底稿来源类型
- 当前推荐值：`kml`
### `playfield.source.url`
- 类型：`string`
- 必填：是
- 说明：KML 文件路径
### `game.mode`
- 类型：`string`
- 必填：是
- 说明：玩法模式
- 顺序赛固定值：`classic-sequential`
### `game.punch.policy`
- 类型：`string`
- 必填：是
- 说明：打点策略
- 当前常用值：
- `enter-confirm`：进入范围后用户再点击确认打点
- `enter`：进入范围自动打点
### `game.punch.radiusMeters`
- 类型：`number`
- 必填：是
- 说明：打点判定半径，单位米
- 建议默认值：`5`
---
## 3. 当前默认逻辑
如果你不写下面这些字段，顺序赛会按当前客户端默认逻辑运行：
- `map.declination`
- 默认按 `0` 处理
- `map.initialView.zoom`
- 默认由客户端初始视口逻辑接管
- `playfield.CPRadius`
- 默认按客户端内置值处理
- `game.session.*`
- 默认手动开始、要求起点打卡、终点打卡
- `game.sequence.skip.*`
- 默认不启用跳点
- `game.guidance.*`
- 默认使用当前引导逻辑
- `resources.*`
- 默认 profile
- `debug.*`
- 默认关闭
---
## 4. 适用场景
这份模板适合：
- 快速验证顺序赛主流程
- 联调地图和 KML
- 后台先跑通最小顺序赛配置
如果要看更完整版本，请继续参考：
- [D:\dev\cmr-mini\doc\config-template-full-current.md](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
- [D:\dev\cmr-mini\event\classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)