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

feat: 收敛玩法运行时配置并加入故障恢复

Browse Source
This commit is contained in:
zhangyan
2026-04-01 13:04:26 +08:00
parent 1635a11780
commit 3ef841ecc7
73 changed files with 8820 additions and 2122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

284
doc/config/配置文档索引.md
View File

@@ -1,220 +1,64 @@
# 配置文档索引
本文档用于汇总当前项目所有与**配置设计、配置样例、配置管理**相关的文档，作为统一入口。
适用对象：
- 客户端开发
- 服务端开发
- 后台管理设计
- 配置录入与联调
---
## 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)
# 配置文档索引
本文档用于汇总当前项目所有与配置设计、配置样例、配置管理相关的文档，并按“公共配置”和“按游戏分类”两层组织。
## 1. 公共配置入口
- [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
字段字典、类型、默认逻辑总入口
- [配置分级总表](D:/dev/cmr-mini/doc/config/配置分级总表.md)
配置项的开放分级与后台推荐策略
- [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
跨玩法公共配置块
- [最小游戏配置模板](D:/dev/cmr-mini/doc/config/最小游戏配置模板.md)
最小通用骨架
- [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
当前共享全量模板
- [后台配置管理方案V2](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)
后台管理与发布方案
- [配置发布说明](D:/dev/cmr-mini/doc/config/配置发布说明.md)
当前 OSS 配置发布命令与默认映射
## 2. 按游戏分类
### 顺序打点
- [游戏说明文档](D:/dev/cmr-mini/doc/games/顺序打点/游戏说明文档.md)
- [规则说明文档](D:/dev/cmr-mini/doc/games/顺序打点/规则说明文档.md)
- [最小配置模板](D:/dev/cmr-mini/doc/games/顺序打点/最小配置模板.md)
- [最大配置模板](D:/dev/cmr-mini/doc/games/顺序打点/最大配置模板.md)
- [全局配置项](D:/dev/cmr-mini/doc/games/顺序打点/全局配置项.md)
- [游戏配置项](D:/dev/cmr-mini/doc/games/顺序打点/游戏配置项.md)
- [样例配置 classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
### 积分赛
- [游戏说明文档](D:/dev/cmr-mini/doc/games/积分赛/游戏说明文档.md)
- [规则说明文档](D:/dev/cmr-mini/doc/games/积分赛/规则说明文档.md)
- [最小配置模板](D:/dev/cmr-mini/doc/games/积分赛/最小配置模板.md)
- [最大配置模板](D:/dev/cmr-mini/doc/games/积分赛/最大配置模板.md)
- [全局配置项](D:/dev/cmr-mini/doc/games/积分赛/全局配置项.md)
- [游戏配置项](D:/dev/cmr-mini/doc/games/积分赛/游戏配置项.md)
- [样例配置 score-o.json](D:/dev/cmr-mini/event/score-o.json)
## 3. 推荐阅读顺序
1. [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
2. [配置分级总表](D:/dev/cmr-mini/doc/config/配置分级总表.md)
3. [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
4. 对应玩法目录下的 [游戏说明文档](D:/dev/cmr-mini/doc/games/顺序打点/游戏说明文档.md) 或 [游戏说明文档](D:/dev/cmr-mini/doc/games/积分赛/游戏说明文档.md)
5. 对应玩法目录下的最小配置模板、最大配置模板、全局配置项、游戏配置项
6. 对应 `event/*.json` 样例
## 4. 维护约定
后续每次新增玩法或新增字段时，建议至少同步这几处：
1. [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
2. [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
3. 对应玩法目录下的规则说明文档
4. 对应玩法目录下的最小配置模板
5. 对应玩法目录下的最大配置模板
6. 对应玩法目录下的全局配置项
7. 对应玩法目录下的游戏配置项
8. 对应玩法的 `event/*.json` 样例