# AudioService 取消语义修复说明

日期：2026-05-20  
范围：`My project/Assets/FlowScope/Runtime/Audio/AudioService.cs`  
优先级：P0 小修复  
结论：建议立即顺手修复

## 问题概述

`AudioService.PlayBgmAsync` 和 `AudioService.PlaySfxAsync` 支持传入 `CancellationToken`，但当前内部 `LoadClipAsync` 会捕获所有异常，并统一包装为 `InvalidOperationException`。

这会导致调用方主动取消音频加载时，拿到的不是 `OperationCanceledException`，而是普通失败异常。

## 影响

取消语义被破坏后，调用方无法可靠区分以下两类情况：

- 生命周期或用户操作导致的正常取消。
- 资源缺失、Addressables 失败、类型不匹配等真实加载错误。

可能造成的问题：

- 正常取消被记录成错误日志。
- UI 或业务层误判为资源加载失败。
- 后续重试、错误兜底、统计埋点出现噪音。
- 框架内不同服务的取消语义不一致，增加异步生命周期排查成本。

## 推荐修改

在 `AudioService.LoadClipAsync` 中单独保留 `OperationCanceledException`，不要包装。

目标代码形态：

```csharp
private async Task<IResourceHandle<AudioClip>> LoadClipAsync(
    string key,
    CancellationToken cancellationToken)
{
    try
    {
        var handle = await _resources.LoadAsync<AudioClip>(key, cancellationToken);
        return ValidateLoadedClip(key, handle);
    }
    catch (OperationCanceledException)
    {
        throw;
    }
    catch (Exception exception)
    {
        throw new InvalidOperationException($"Failed to load audio clip '{key}'.", exception);
    }
}
```

## 测试建议

在 `AudioServiceTests` 中补充异步取消测试。

建议覆盖：

1. `PlayBgmAsync_WhenCanceled_ThrowsOperationCanceledException`
2. `PlaySfxAsync_WhenCanceled_ThrowsOperationCanceledException`

测试要点：

- 创建 `CancellationTokenSource`。
- 调用 `Cancel()`。
- 调用 `PlayBgmAsync` 或 `PlaySfxAsync`。
- 断言抛出 `OperationCanceledException`。
- 断言没有创建新的 `AudioSource`。

示例结构：

```csharp
[UnityTest]
public IEnumerator PlayBgmAsync_WhenCanceled_ThrowsOperationCanceledException()
{
    var service = CreateService();
    using var cts = new CancellationTokenSource();
    cts.Cancel();
    var sourceCountBeforePlay = Object.FindObjectsOfType<AudioSource>().Length;

    yield return ThrowsAsync<OperationCanceledException>(
        service.PlayBgmAsync("bgm-a", cancellationToken: cts.Token));

    Assert.That(Object.FindObjectsOfType<AudioSource>().Length, Is.EqualTo(sourceCountBeforePlay));
}
```

如果现有测试工具方法只支持 `Func<Task>`，也可以按当前测试文件风格新增一个接收 `Task` 的 `ThrowsAsync<TException>` helper。

## 验收标准

- `PlayBgmAsync` 在取消时抛出 `OperationCanceledException`。
- `PlaySfxAsync` 在取消时抛出 `OperationCanceledException`。
- 取消时不创建 `AudioSource`。
- 取消时不把异常包装成 `InvalidOperationException`。
- 现有 PlayMode 音频测试继续通过。

## 后续备注

该问题不是架构阻塞项，但修复成本很低。建议本轮直接修掉，避免后续异步服务取消语义不一致。