---
description: Godot 数据驱动内容、数据访问、校验与存档兼容约定
globs: "**/*.{gd,tres,res,csv,json}"
alwaysApply: false
---

# Godot 数据系统

## 数据驱动边界

- 需要由策划或内容人员独立调整的参数、实体定义和效果配置，应放入项目采用的数据源，不散落为脚本字面量。
- 先复用项目已有的 `Resource`、CSV、JSON 或其他数据管线；项目尚未采用数据驱动时，根据实际复用需求选择最小方案，不强制新增格式或仓库层。
- 技术常量、枚举、协议版本和与内容无关的安全默认值可以留在代码中，并用名称或注释说明用途。
- 不明确某个数值属于内容还是技术约束时，先查现有数据定义和调用方。

## 加载与访问

- 为数据定义稳定 ID、字段类型、必填项和默认值；加载边界统一做格式与引用校验。
- 解析失败应包含数据源、记录 ID 和字段名；可恢复问题使用安全默认值并报告，不可恢复问题尽早失败。
- 若项目已有 Store、Repository 或缓存层，公开查询入口统一经过该层，并提供测试可用的清理或重载能力。
- 调用方不应重复解析同一数据源，也不应依赖数据文件中的偶然顺序。
- 新增可配置行为时优先扩展既有注册或组合机制，避免在多个调用点堆叠同类条件分支。

## 存档与兼容

- 持久化数据携带明确版本；读取时对缺失字段提供默认值，并为不兼容结构提供显式转换。
- 只保存恢复状态所需的数据，不序列化场景节点引用或临时缓存。
- 数据结构变化时同时更新加载、保存、校验和回归测试。