P0-6: ISaveService 需求详细文档

对齐说明

本文档以 docs/requirements/p0-requirements-set.md 为准。P0 存档系统只提供本地轻量存取；云存档、加密、压缩、复杂迁移和冲突解决通过后续扩展接入。

目标

提供本地保存、读取、删除和存在性检查能力，支撑 P0 Sample 的 Data 持久化。

接口

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。
多存档槽管理。
自动存档。
云存档完整实现。
本地 + 云双写。
加密。
压缩。
存档版本迁移。
冲突解决。

扩展方向

后续通过以下接口扩展：

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`

依赖关系

ISaveService
├── ISaveStorage
├── ISaveSerializer
├── JSON 库
└── R3 JSON Converter

2.7 KiB Raw Permalink Blame History Unescape Escape