# 📦 DataStorage 数据存储模块

## ✨ 简介

该模块是一个基于 Unity + Easy Save 的本地数据存储系统，具备：

- ✅ 本地缓存机制（避免频繁磁盘 IO）
- ✅ 自动保存机制（按时间间隔或调用次数）
- ✅ 云同步支持（支持上传 JSON，或导入云端数据）
- ✅ 数据版本控制
- ✅ 类型安全的 `DataStorage<T>` 封装
- ✅ 可调试的 GM 工具接口

------

## 📁 使用说明

### 🔹 1. 定义数据键

在模块初始化之前，使用 `DataKeyDic.Register` 注册数据键名（通常在 `DataStorage<T>` 构造时自动完成）：

```c#
var playerName = new DataStorage<string>("PlayerName", "Guest");
playerName.Value = "Pius123";
```

或使用保存回调监听值变化：

```c#
var coins = new DataStorage<int>("CoinAmount", 0, (oldVal, newVal) => {
    Debug.Log($"金币变化：{oldVal} -> {newVal}");
});
```

### 🔹 2. 保存和读取数据

```c#
coins.Value = 100;                    // 保存数据（自动缓存 + 标记待保存）
var coinAmount = coins.Value;        // 从缓存读取（或回退至本地/云端）
coins.Save();                        // 强制保存（即使值没变）
```

也可直接使用底层 API 操作(不建议)：

```c#
DataManager.Instance.SaveData("Level", 5);
int level = DataManager.Instance.LoadData("Level", 1);
```

### 🔹 3. 自动保存逻辑

模块会在以下时机自动保存数据到磁盘（使用 Easy Save）：

- ⏱ 每隔 15 秒（可配置）
- 🔁 累积 `SaveData` 达到 20 次（可配置）
- 🚫 App 暂停、退出时
- 📡 数据版本每增加两次触发一次 `_saveCallback`（用于云上传）

------

## 🌐 云同步支持

### ✅ 导出 JSON 上传云端

```c#
DataManager.Instance.AddSaveCallback((json, version, onQuit) => {
    // 上传 json 到云端，携带版本 version
});
```

每次本地数据保存时（根据频率控制）会自动回调此方法。

### ✅ 从云端导入数据

```c#
DataManager.Instance.ImportFromJson(jsonFromServer, versionFromServer);
```

- 若云端版本 > 本地版本：自动覆盖并保存到本地
- 若云端版本 < 本地版本：会自动触发 `_saveCallback` 上传本地数据覆盖云端

------

## 🔧 GM 调试接口（可选）

调用 `DataManager.Instance.Init()` 可注册 GM 工具按钮：

- 🧹 清空所有数据
- 🗂 打印所有缓存键值对

------

## 🧠 数据结构概览

| 类名                         | 说明                                           |
| ---------------------------- | ---------------------------------------------- |
| `DataManager`                | 核心数据存储与调度管理（自动保存、版本、缓存） |
| `DataStorage<T>`             | 泛型数据封装，提供属性式访问与变更通知         |
| `DataKeyDic` / `DataKeyBase` | 注册键名与云同步标记支持                       |
| `ES3`                        | 第三方 Easy Save 工具（需另行导入）            |



------

## 📝 配置项

| 名称                      | 默认值 | 说明                 |
| ------------------------- | ------ | -------------------- |
| `InitialAutoSaveInterval` | `15s`  | 自动保存时间间隔     |
| `SaveThreshold`           | `20次` | 自动保存调用次数阈值 |
| `DataVersion`             | `1`    | 数据版本号，内部递增 |



------

## 🔍 调试建议

- 使用 `DebugAllKeys()` 打印所有持久化键值
- 使用 `DebugCache()` 打印当前缓存数据
- 检查 `Log.Info/Error` 输出（默认已集成日志标记）

------

## 📦 依赖项

- **Easy Save 3**：第三方持久化框架
- **Newtonsoft.Json**：JSON 序列化与反序列化
- **自定义框架组件**（如 `SingletonMonoBehaviour`、`Log`、`CommonUtils`、`GMTool` 等）

------

## 📌 注意事项

- 云同步仅同步标记为 `CloudSave = true` 的键
- `DataStorage<T>` 会自动触发注册，但手动操作建议提前注册
- 非线程安全，不建议多线程并发调用
- 建议在游戏入口或登录成功后初始化模块并导入云数据