# 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
```