97 lines
2.7 KiB
Markdown
97 lines
2.7 KiB
Markdown
# P0-6: ISaveService 需求详细文档
|
||
|
||
## 对齐说明
|
||
|
||
本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 存档系统只提供本地轻量存取；云存档、加密、压缩、复杂迁移和冲突解决通过后续扩展接入。
|
||
|
||
## 目标
|
||
|
||
提供本地保存、读取、删除和存在性检查能力，支撑 P0 Sample 的 Data 持久化。
|
||
|
||
## 接口
|
||
|
||
```csharp
|
||
public interface ISaveService
|
||
{
|
||
Task SaveAsync<T>(string key, T data, CancellationToken cancellationToken);
|
||
Task<T> LoadAsync<T>(string key, T defaultValue, CancellationToken cancellationToken);
|
||
void Delete(string key);
|
||
bool Exists(string key);
|
||
}
|
||
```
|
||
|
||
## 默认实现
|
||
|
||
P0 默认实现二选一：
|
||
|
||
| 实现 | 说明 |
|
||
|------|------|
|
||
| `FileSaveStorage` | 使用本地文件，适合普通存档 |
|
||
| `PlayerPrefsSaveStorage` | 使用 PlayerPrefs，适合小型数据 |
|
||
|
||
P0 默认序列化为 JSON，并支持 R3 Data 中的 `ReactiveProperty<T>` / `ReactiveCollection<T>` 转换。
|
||
|
||
## 行为规则
|
||
|
||
- `LoadAsync` 读取不存在 key 时返回 `defaultValue`。
|
||
- 反序列化失败返回 `defaultValue` 并记录警告。
|
||
- 存储读取失败返回 `defaultValue` 并记录警告。
|
||
- 写入失败抛异常，异常包含 key。
|
||
- `Delete` 删除不存在 key 时静默忽略。
|
||
- `Exists` 只检查当前默认存储后端。
|
||
|
||
## 暂不做
|
||
|
||
- `ListKeys`。
|
||
- 多存档槽管理。
|
||
- 自动存档。
|
||
- 云存档完整实现。
|
||
- 本地 + 云双写。
|
||
- 加密。
|
||
- 压缩。
|
||
- 存档版本迁移。
|
||
- 冲突解决。
|
||
|
||
## 扩展方向
|
||
|
||
后续通过以下接口扩展：
|
||
|
||
```csharp
|
||
public interface ISaveStorage
|
||
{
|
||
Task WriteAsync(string key, byte[] data, CancellationToken cancellationToken);
|
||
Task<byte[]> ReadAsync(string key, CancellationToken cancellationToken);
|
||
void Delete(string key);
|
||
bool Exists(string key);
|
||
}
|
||
|
||
public interface ISaveSerializer
|
||
{
|
||
byte[] Serialize<T>(T data);
|
||
T Deserialize<T>(byte[] bytes);
|
||
}
|
||
```
|
||
|
||
## 验收标准
|
||
|
||
| # | 标准 | 通过条件 |
|
||
|---|------|---------|
|
||
| 1 | 保存和读取 | Save 后 Load 返回等价数据 |
|
||
| 2 | 默认值 | 不存在 key 时返回传入 defaultValue |
|
||
| 3 | 删除 | Delete 后 Exists 为 false，Load 返回 defaultValue |
|
||
| 4 | Exists | 已保存 key 返回 true，未保存 key 返回 false |
|
||
| 5 | ReactiveProperty 序列化 | 保存 JSON 不包含 ReactiveProperty 内部状态 |
|
||
| 6 | 反序列化失败 | 返回 defaultValue 并记录警告 |
|
||
| 7 | 写入失败 | 抛异常并包含 key |
|
||
| 8 | 取消保存/加载 | CancellationToken 取消时抛 `OperationCanceledException` |
|
||
|
||
## 依赖关系
|
||
|
||
```text
|
||
ISaveService
|
||
├── ISaveStorage
|
||
├── ISaveSerializer
|
||
├── JSON 库
|
||
└── R3 JSON Converter
|
||
```
|