文档记录

docs/requirements/p0-audioservice.md

@@ -0,0 +1,95 @@
+# 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
+```