mini-prog/doc/config-docs-index.md

# 配置文档索引

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

适用对象：

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

---

1. 配置设计总方案

config-design-proposal.md

作用：

• 说明为什么配置要按 app / map / playfield / game / resources / debug 分层
• 说明 KML 和配置的职责边界
• 说明为什么上位概念用 playfield
• 适合做总体架构参考

适合阅读时机：

• 设计配置结构
• 设计客户端读取链
• 和后端讨论顶层模型时

---

2. 配置选项字典

config-option-dictionary.md

作用：

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

适合阅读时机：

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

---

3. 默认配置模板

config-default-template.md

作用：

• 提供当前推荐的默认配置模板
• 包含顺序赛和积分赛的基础默认示例
• 用于服务端、后台、联调时直接起步

适合阅读时机：

• 新建一份活动配置
• 想直接照着填配置
• 想知道最小可运行模板长什么样

---

4. 按玩法拆分的配置模板文档

config-template-classic-sequential.md

作用：

• 解释顺序赛配置结构
• 说明顺序赛的必填字段和默认值
• 适合给后端和后台做顺序赛专项参考

config-template-score-o.md

作用：

• 解释积分赛配置结构
• 说明积分赛的必填字段和默认值
• 适合给后端和后台做积分赛专项参考

---

5. 运行中的样例配置

event/classic-sequential.json

作用：

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

event/score-o.json

作用：

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

---

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

backend-config-management-proposal.md

作用：

• 第一版后台配置管理建议
• 适合了解 Map / Playfield / GameMode / ResourcePack / Event 这套核心对象

backend-config-management-v2.md

作用：

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

推荐优先看这一份。

---

7. 推荐阅读顺序

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

1. config-design-proposal.md
2. config-option-dictionary.md
3. config-default-template.md
4. event/classic-sequential.json
5. event/score-o.json
6. backend-config-management-v2.md

---

8. 维护约定

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

1. config-option-dictionary.md
2. config-default-template.md
3. 对应玩法的 event/*.json 样例
4. 如果涉及顶层结构变化，再更新 config-design-proposal.md

这样可以保证：

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

保持一致。