FlowScope/docs/requirements/p0-audioservice.md

P0-9: IAudioService 需求详细文档

对齐说明

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

目标

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

接口

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 池

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

依赖关系

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