mini-prog/doc/config/配置文档索引.md

# 配置文档索引

本文档用于汇总当前项目所有与配置设计、配置样例、配置管理相关的文档，作为统一入口。

适用对象：

• 客户端开发
• 服务端开发
• 后台管理设计
• 配置录入与联调

---

1. 配置核心结构

当前项目的配置主入口已经稳定在：

{
  "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

---

2. 配置选项字典

config-option-dictionary.md

作用：

• 列出当前客户端已经支持或已预留的配置项
• 说明每个字段的类型、含义、默认逻辑
• 作为后续新增字段时的持续维护文档

适合阅读时机：

• 想知道某个字段是否已实现
• 想知道字段应该怎么写
• 想确认默认行为时

track-visualization-proposal.md

作用：

• 说明 none / full / tail 三种轨迹模式
• 说明拖尾轨迹的默认策略与推荐参数
• 说明当前轨迹样式的配置结构

gps-marker-style-system-proposal.md

作用：

• 说明 GPS 点样式系统的目标分层
• 说明默认样式、朝向小三角和品牌 logo 扩展思路
• 说明第一阶段最小实现字段和长期演进方向

gps-marker-animation-system-proposal.md

作用：

• 说明 GPS 点动画系统的状态分层
• 说明 idle / moving / fast-moving / warning 的第一阶段实现思路
• 说明动画 profile、运行时内部字段和 standard / lite 降级策略

---

3. 当前推荐模板

config-template-minimal-game.md

作用：

• 提供“最小可跑”的游戏配置模板
• 去掉绝大部分选配项
• 适合快速起步、联调和排查配置链

config-template-minimal-classic-sequential.md

作用：

• 提供顺序赛最小可跑模板
• 适合快速起顺序赛活动

config-template-minimal-score-o.md

作用：

• 提供积分赛最小可跑模板
• 适合快速起积分赛活动

config-template-full-current.md

作用：

• 提供“当前开发状态最全”的配置模板
• 汇总目前客户端已实现或已消费的主要字段
• 适合后端、后台和联调统一对齐

---

4. 运行中的样例配置

event/classic-sequential.json

作用：

• 当前顺序赛样例配置
• 可直接联调
• 已包含控制点内容覆盖示例

event/score-o.json

作用：

• 当前积分赛样例配置
• 可直接联调
• 已包含分值、起终点内容、点击内容示例

---

5. 后台与服务端配置管理方案

backend-config-management-v2.md

作用：

• 在“配置项变化频繁”前提下重写的后台方案
• 更强调：
  • 稳定骨架
  • jsonb
  • 版本
  • 发布
  • 透传未知字段

推荐优先看这一份。

---

6. 推荐阅读顺序

如果你是第一次接触这套配置体系，建议按这个顺序看：

1. 本页“配置核心结构”一节
2. config-option-dictionary.md
3. config-template-minimal-game.md
4. config-template-minimal-classic-sequential.md
5. config-template-minimal-score-o.md
6. config-template-full-current.md
7. event/classic-sequential.json
8. event/score-o.json
9. backend-config-management-v2.md

---

7. 维护约定

后续每次新增配置能力时，建议至少同步更新这几处：

1. config-option-dictionary.md
2. config-template-minimal-game.md
3. config-template-minimal-classic-sequential.md
4. config-template-minimal-score-o.md
5. config-template-full-current.md
6. 对应玩法的 event/*.json 样例
7. 如果涉及顶层结构变化，先更新本页“配置核心结构”一节，再视情况补充归档讨论稿

这样可以保证：

• 文档
• 样例
• 代码
• 后台录入

保持一致。

---

8. 已归档文档

下列文档仍保留在归档目录，但不再作为当前主入口：

• config-default-template.md
• config-design-proposal.md
• config-template-classic-sequential.md
• config-template-score-o.md
• backend-config-management-proposal.md