文档记录

docs/requirements/p0-saveservice.md

@@ -0,0 +1,96 @@
+# 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
+```