# FlowScope Addressables 集成验收记录

日期：2026-06-04

## 验收目的

本文用于补齐 P2 第一阶段的 Addressables 真实集成验收缺口。目标不是重新设计资源系统，而是确认当前 `FlowScope.Addressables.AddressablesResourceBackend` 能通过真实 Addressables key 完成加载、释放和错误诊断。

## 项目配置

已确认：

- `My project/Packages/manifest.json` 包含 `com.unity.addressables`，当前版本为 `1.21.21`。
- `My project/Assets/FlowScope/Addressables/FlowScope.Addressables.asmdef` 引用 `FlowScope.Runtime`、`Unity.Addressables`、`Unity.ResourceManager`。
- `My project/Assets/FlowScope/Tests/PlayMode/FlowScope.Tests.PlayMode.asmdef` 引用 `FlowScope.Addressables`。
- 当前项目已生成 `My project/Assets/AddressableAssetsData`。
- `My project/ProjectSettings/EditorBuildSettings.asset` 已登记 Addressables settings config object。

## 测试资源

真实 Addressables 测试资源：

- 路径：`Assets/FlowScope/Tests/PlayMode/Resources/Fixtures/Addressables/FlowScopeAddressablesText.txt`
- 内容：`FlowScope Addressables Acceptance`
- GUID：`7e04733ce9dab74459592d3bd99fcafd`
- Addressables group：`Default Local Group`
- Addressables key：`FlowScope.Tests.Addressables.Text`
- 资源类型：`TextAsset`

`Default Local Group.asset` 中已确认存在：

```yaml
m_GUID: 7e04733ce9dab74459592d3bd99fcafd
m_Address: FlowScope.Tests.Addressables.Text
```

## 自动化验收

已在 `My project/Assets/FlowScope/Tests/PlayMode/Resources/AddressablesResourceBackendTests.cs` 补充真实 PlayMode 集成测试：

- `LoadAsync_WithRealTextAssetKey_LoadsTextAsset`
- `LoadAsync_WithMissingKey_ThrowsDiagnosticException`
- `LoadAsync_WithMismatchedType_ThrowsDiagnosticException`

覆盖范围：

- `AddressablesResourceBackend.LoadAsync<TextAsset>` 能通过真实 key 加载真实 `TextAsset`。
- `AddressablesResourceBackend.Release` 能释放已加载资源。
- 缺失 key 会产生可捕获诊断异常，并包含缺失 key。
- 类型不匹配会产生可捕获诊断异常，并包含 key 和请求类型。

本轮同时修复了 `AddressablesResourceBackend.LoadAsync<T>` 的失败状态处理：当 Addressables handle 存在 `OperationException`、`Status` 不是 `Succeeded` 或 `Result` 为 `null` 时，backend 会抛出包含 key、请求类型和 backend 名称的 `InvalidOperationException`。

## 验收结果

用户已在 Unity Test Runner 中执行全量 EditMode / PlayMode，结果全绿。

本轮针对 Addressables 集成用例的最终结果：

| 项目 | 结果 | 证据 |
| --- | --- | --- |
| 真实 `LoadAsync<TextAsset>` | 通过 | `FlowScope.Tests.Addressables.Text` 加载真实 `TextAsset` |
| `Release<TextAsset>` | 通过 | 成功释放已加载资源，未产生未处理日志 |
| 缺失 key 诊断 | 通过 | `FlowScope.Tests.Addressables.Missing` 产生可捕获异常 |
| 类型不匹配诊断 | 通过 | `TextAsset` key 以 `GameObject` 请求时产生可捕获异常 |
| Unity Test Runner EditMode | 通过 | 用户反馈全量 EditMode 全绿 |
| Unity Test Runner PlayMode | 通过 | 用户反馈全量 PlayMode 全绿 |

## 剩余注意事项

- 当前 Addressables 测试资源已整理到 `Resources/Fixtures/Addressables` 路径下，为后续 package `Tests~` 迁移去掉临时目录命名。
- `Assets/FlowScope/Tests/PlayMode/Resources/Fixtures` 当前只剩空目录 meta，属于提交前清理候选。
- 当前验收仍在主项目内完成；P2 后续 package 阶段还需要在干净 Unity 项目中验证本地 package path 或 Git URL 安装。

## 结论

P2 第一阶段的 Addressables 真实集成验收已完成。当前不再只是编译通过或人工步骤文档，而是已有真实 PlayMode 自动化测试覆盖成功加载、释放、缺失 key 和类型不匹配诊断。