UnityAI/modules/frameworks/数据配置框架.md

# 数据 / 配置框架

## 分类

- 核心框架

## 目的

管理 XLSX 配置表源、解析、生成运行时数据和读取 API。

---

## 核心路径

- 配置源：`XLSX_SRC/CN/`、`XLSX_SRC/EN/`
- 生成设置：`ProjectSettings/ZYF/ZYXlsx/ZYXlsxProjectSettings.asset`
- Resolve Asset：`Assets/Editor/XLSX_SRC/Resolve/ZYXlsx/`
- 输出数据：`Assets/AutoBuildAsset/{Editor,Hotfix}/AutoFrame/Google.Protobuf/XLSX_SRC/<语言>/`
- 输出代码：`Assets/AutoBuildScript/{Editor,General,Hotfix}/AutoFrame/Google.Protobuf/XLSX_Script/`

---

## 常见配置表

| 表名 | 用途 |
|---|---|
| `Constants.xlsx` | 常量配置 |
| `EntityConfig.xlsx` | 实体配置 |
| `Gift.xlsx` | 礼包/奖励配置 |
| `Resource.xlsx` | 资源/道具配置 |
| `SkillGroup.xlsx` | 技能组配置 |
| `SkillReleaser.xlsx` | 技能释放器配置 |
| `SkillTrigger.xlsx` | 技能触发器配置 |
| `SkillUp.xlsx` | 技能升级配置 |
| `Sounds.xlsx` | 音效配置 |
| `Wave.xlsx` | 波次配置（业务示例） |

---

## 运行时加载调用链

```text
HFGameStart.LoadDB()
  -> Hotfix_ZYXlsx_GoogleProtobuf_Helper.instance.LoadAllXlsx(OnLoadDbFinish)
  -> 遍历 enZYXlsxSheet
  -> GetExistsDataLang / GetSheetMemoryPackBufferFilePath
  -> HFFunCatalogue.Asset.LoadDBHelper(path.GetHashCode(), path, callback)
  -> 缓存 sheet bytes 到 mDicLangSheetBytes
```

---

## 运行时读取 API

```csharp
// 按主键读取单条
HFFunCatalogue.NDB.ds_xxx.ReadTableByPK(pk);

// 读取全表
HFFunCatalogue.NDB.ds_xxx.ReadTableList();

// 读取行列式数据
HFFunCatalogue.NDB.ds_xxx.ReadTableDeterminant();
```

---

## 使用规则

- 改表后必须重新生成。
- 配置读取必须在 `LoadAllXlsx` 完成后。
- 主键/全表/常量分别用对应 API。
- 禁止高频全表读取。
- id 优先来自表/协议/常量，禁止魔法数字。
- 高频配置在 manager 初始化或窗口打开时缓存。
- 多语言字段需补齐。

---

## 变更清单

1. 修改源表（`XLSX_SRC/CN/`、`XLSX_SRC/EN/`）。
2. 确认 `ProjectSettings/ZYF/ZYXlsx/ZYXlsxProjectSettings.asset` 与 Resolve 配置。
3. 通过 Unity 菜单 `StrayFog → XLSX → Generate Runtime Data`（或对应 MCP 白名单命令）重新生成。
4. 检查输出数据目录 `Assets/AutoBuildAsset/{Editor,Hotfix}/AutoFrame/Google.Protobuf/XLSX_SRC/<语言>/`。
5. 检查输出代码目录 `Assets/AutoBuildScript/{Editor,General,Hotfix}/AutoFrame/Google.Protobuf/XLSX_Script/`。
6. 编译 `GameGeneral`、`GameHF`、`SFMono` 等受影响程序集。
7. 运行时验证：确认 `HFGameStart.LoadDB()` 成功且读取 API 返回预期。
8. 更新本文档与 [模块索引](../模块索引.md)。

## 验证

- 生成器执行无 Error。
- 受影响程序集编译通过。
- 运行时 `LoadAllXlsx` 回调正常触发。
- 关键表（如 `EntityConfig`、`SkillGroup`）按主键读取结果正确。

## 当前状态

- 待验证

---

## 相关模块

- [实体系统](实体系统/README.md)
- [技能系统](技能系统/README.md)
- [资源管理](资源管理/README.md)

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 |
| [modules/frameworks/实体系统/README.md](实体系统/README.md) | 实体配置来自配置表 |
| [modules/frameworks/技能系统/README.md](技能系统/README.md) | 技能配置来自配置表 |
| [modules/frameworks/资源管理/README.md](资源管理/README.md) | 配置资源加载依赖资源管理 |
| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |