文档记录

docs/requirements/p0-resourceservice.md

@@ -0,0 +1,104 @@
+# P0-7: IResourceService 需求详细文档
+
+## 对齐说明
+
+本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 资源系统包含引用计数和资源组，因为它直接影响 Feature 释放正确性；但 P0 只实现 Addressables 默认后端，其他后端通过插件扩展。
+
+## 目标
+
+提供异步资源加载、同 key 并发合并、引用计数和资源组释放能力。
+
+## 接口
+
+```csharp
+public interface IResourceService
+{
+    Task<IResourceHandle<T>> LoadAsync<T>(
+        string key,
+        CancellationToken cancellationToken)
+        where T : class;
+
+    IResourceGroup CreateGroup();
+}
+
+public interface IResourceHandle<T> : IDisposable where T : class
+{
+    string Key { get; }
+    T Asset { get; }
+    bool IsDisposed { get; }
+}
+
+public interface IResourceGroup : IDisposable
+{
+    void Add<T>(IResourceHandle<T> handle) where T : class;
+    int Count { get; }
+}
+```
+
+## 行为规则
+
+- `LoadAsync<T>` 加载失败时抛异常，异常包含 key 和后端类型。
+- 同 key 同类型并发加载只触发一次底层加载。
+- 每次 `LoadAsync` 返回独立 handle。
+- 每个 handle Dispose 时引用计数减一。
+- 最后一个 handle Dispose 时释放底层资源。
+- `IResourceGroup.Dispose` 释放组内所有 handle。
+- 重复 Dispose 不抛异常。
+- Group 重复 Add 同一个 handle 时忽略。
+- Dispose 后访问 `Asset` 的行为必须固定为返回 null。
+
+## 默认后端
+
+P0 默认只支持 Addressables。
+
+```text
+IResourceService
+└── AddressablesResourceBackend
+```
+
+## 暂不做
+
+- Resources 后端。
+- AssetBundle 后端。
+- YooAsset 后端。
+- 资源预热。
+- 下载进度回调。
+- 资源优先级。
+- 资源版本管理。
+- 编辑器资源扫描和分析工具。
+
+## 扩展方向
+
+P1/P2 通过后端接口扩展：
+
+```csharp
+public interface IResourceBackend
+{
+    Task<T> LoadAsync<T>(string key, CancellationToken cancellationToken)
+        where T : class;
+
+    void Release(string key, object asset);
+}
+```
+
+## 验收标准
+
+| # | 标准 | 通过条件 |
+|---|------|---------|
+| 1 | 正常加载 | LoadAsync 返回 handle，Asset 可用 |
+| 2 | 加载失败 | 不存在 key 抛异常并包含 key |
+| 3 | 引用计数 | 同 key 加载两次，最后一个 handle Dispose 后才释放底层资源 |
+| 4 | 并发合并 | 同 key 并发 LoadAsync 只触发一次底层加载 |
+| 5 | Group 释放 | Group Dispose 后组内 handle 全部释放 |
+| 6 | 重复 Dispose | handle/group 重复 Dispose 不抛异常 |
+| 7 | Dispose 后 Asset | 返回 null |
+| 8 | 取消加载 | CancellationToken 取消时抛 `OperationCanceledException` |
+
+## 依赖关系
+
+```text
+IResourceService
+├── Addressables
+├── CancellationToken
+└── 被 Feature / UIManager / AudioService 依赖
+```