# P0-9: IAudioService 需求详细文档

## 对齐说明

本文档以 `docs/requirements/p0-requirements-set.md` 为准。P0 音频系统提供基础 BGM/SFX 能力和轻量 `IAudioHandle`，但不做完整音频框架。

## 目标

提供基础音频播放能力，包括 BGM 播放/停止、SFX 播放、音量控制、静音、简单 SFX AudioSource 池和 BGM 淡入淡出。

## 接口

```csharp
public interface IAudioService
{
    IAudioHandle PlayBgm(string key, bool loop = true, float fadeIn = 0f);
    IAudioHandle PlaySfx(string key);
    void StopBgm(float fadeOut = 0f);
    void SetBgmVolume(float volume);
    void SetSfxVolume(float volume);
    void SetMute(bool mute);
}

public interface IAudioHandle
{
    void Stop(float fadeOut = 0f);
    bool IsPlaying { get; }
}
```

## 行为规则

- 同一时间只有一首 BGM。
- 播放新 BGM 时停止旧 BGM。
- `fadeIn` 和 `fadeOut` 使用线性插值。
- SFX 可同时播放多个。
- SFX 使用简单 AudioSource 池。
- 音量参数 clamp 到 `[0, 1]`。
- 最终音量 = 通道音量 * 静音系数。
- 音频资源通过 `IResourceService` 加载。
- 播放失败时抛异常并包含 key。

## SFX 池

```csharp
public sealed class AudioServiceConfig
{
    public int SfxPoolSize = 10;
    public bool ReuseOldestWhenExhausted = true;
}
```

规则：

- 池未满时创建或复用 AudioSource。
- 池耗尽且允许复用时，复用最早播放完毕或最旧的 AudioSource。
- 池耗尽且不允许复用时，记录警告并跳过本次 SFX。

## 暂不做

- 单个音频 Pause/Resume。
- 单个音频 Volume。
- AudioMixer 分组。
- 3D 空间音频。
- 动态音乐。
- 语音/对话系统。
- 音频配置表。
- 编辑器音频检查工具。

## 验收标准

| # | 标准 | 通过条件 |
|---|------|---------|
| 1 | BGM 播放 | PlayBgm 后 BGM 正常播放 |
| 2 | BGM 切换 | 播放新 BGM 时旧 BGM 停止 |
| 3 | BGM 淡入 | fadeIn > 0 时线性渐入 |
| 4 | BGM 停止 | StopBgm 后 BGM 停止 |
| 5 | BGM 淡出 | fadeOut > 0 时线性渐出后停止 |
| 6 | SFX 播放 | PlaySfx 后音效播放 |
| 7 | SFX 并发 | 多个 SFX 可同时播放 |
| 8 | SFX 池 | 多次播放不无限创建 AudioSource |
| 9 | Handle Stop | handle.Stop 后对应音频停止 |
| 10 | IsPlaying | 播放中 true，停止后 false |
| 11 | 音量 clamp | 超出范围时自动 clamp |
| 12 | 静音 | SetMute(true) 后所有音频静音 |
| 13 | 加载失败 | 不存在 key 抛异常并包含 key |

## 依赖关系

```text
IAudioService
├── IResourceService
├── Unity AudioSource / AudioClip
└── 可选 MonoBehaviour Update/Coroutine 驱动 fade
```