docs(audio): 添加 oto/v3 重构设计和实施计划文档

- 设计文档：架构设计、API 设计、并发模型
- 实施计划：16 个任务，完整的实施步骤
- 验收标准：测试覆盖、功能验证、性能指标

docs/superpowers/specs/2026-04-08-oto-audio-refactor-design.md

@@ -0,0 +1,429 @@
+# oto/v3 音频播放重构设计
+
+**日期:** 2026-04-08
+**作者:** Claude
+**状态:** 设计阶段
+
+## 1. 概述
+
+### 1.1 重构目标
+
+使用 `oto/v3` 完全重构项目中的音频播放功能,移除 `beep/v2` 依赖,解决音频播放问题。
+
+### 1.2 重构范围
+
+- ✅ 所有音频播放功能: WAV/MP3 一次性播放、BGM 循环播放、待机音频
+- ✅ 保持现有业务逻辑不变
+- ✅ 遵循 oto/v3 官方最佳实践
+- ✅ 高效、简洁、优雅的实现
+
+### 1.3 当前问题
+
+- 音频未正确播放(具体表现待重构后验证)
+- 依赖 `beep/v2` 中间层,增加复杂度
+- 代码不够简洁优雅
+
+## 2. 架构设计
+
+### 2.1 整体结构
+
+```
+业务层 (middleware/routes)
+    ↓
+音频播放层 (pkg/audio)
+    ↓
+oto/v3 核心层
+```
+
+**设计原则:**
+- 单一 oto.Context: 全局初始化一次,所有播放共享
+- 独立 Player: 每次播放创建新的 Player,互不干扰
+- 格式解码器: MP3/WAV 解码器直接传给 oto.Player
+- 直接流式播放: 无需预先转 PCM,oto 自动处理
+- 自动重采样: oto 会自动处理采样率不匹配的情况
+
+### 2.2 依赖管理
+
+**移除:**
+- `github.com/gopxl/beep/v2`
+
+**保留并改为直接依赖:**
+- `github.com/ebitengine/oto/v3`
+
+**保留:**
+- `github.com/hajimehoshi/go-mp3`
+
+**新增:**
+- `github.com/go-audio/wav` - WAV 解码
+
+## 3. 核心组件设计
+
+### 3.1 全局状态管理
+
+```go
+var (
+    otoCtx  *oto.Context
+    otoOnce sync.Once
+)
+
+// 音频配置常量
+const (
+    DefaultSampleRate   = 44100 // 采样率
+    DefaultChannelCount = 2      // 声道数(立体声)
+)
+
+func initContext() (*oto.Context, error) {
+    var initErr error
+    otoOnce.Do(func() {
+        op := &oto.NewContextOptions{}
+        op.SampleRate = DefaultSampleRate
+        op.ChannelCount = DefaultChannelCount
+        op.Format = oto.FormatSignedInt16LE
+
+        var ready <-chan struct{}
+        otoCtx, ready, initErr = oto.NewContext(op)
+        if initErr != nil {
+            return
+        }
+        <-ready // 等待音频设备就绪
+        zap.S().Infoln("oto/v3 音频系统就绪")
+    })
+    return otoCtx, initErr
+}
+```
+
+**设计说明:**
+- ✅ 使用 `sync.Once` 确保全局 Context 只初始化一次
+- ✅ 使用 `oto.NewContext()` 返回的 ready channel,而非包级变量
+- ✅ 返回 error 给调用者处理,而非 panic
+
+### 3.2 一次性播放(阻塞式)
+
+**关键实现点:**
+- oto.Context 配置为 44100Hz,16bit,立体声
+- MP3/WAV 解码器直接传给 oto.NewPlayer()
+- 播放完成后会自动停止,IsPlaying() 返回 false
+- context 取消时,defer player.Close() 确保资源释放
+- goroutine 会在 player.Close() 后自然退出,无泄漏风险
+
+**PlayWav:** 播放 WAV 文件,阻塞直到完成或 context 取消
+
+```go
+func PlayWav(ctx context.Context, r io.ReadCloser) error {
+    otoCtx, err := initContext()
+    if err != nil {
+        return fmt.Errorf("音频上下文初始化失败: %w", err)
+    }
+
+    dec, err := wav.NewDecoder(r)
+    if err != nil {
+        r.Close()
+        return fmt.Errorf("WAV 解码失败: %w", err)
+    }
+    defer r.Close()
+
+    player := otoCtx.NewPlayer(dec)
+    defer player.Close()
+
+    player.Play()
+
+    done := make(chan struct{})
+    go func() {
+        for player.IsPlaying() {
+            time.Sleep(time.Millisecond)
+        }
+        close(done)
+    }()
+
+    select {
+    case <-done:
+        return nil
+    case <-ctx.Done():
+        return ctx.Err()
+    }
+}
+```
+
+**PlayMP3:** 播放 MP3 文件,阻塞直到完成或 context 取消
+
+```go
+func PlayMP3(ctx context.Context, r io.ReadCloser) error {
+    otoCtx, err := initContext()
+    if err != nil {
+        return fmt.Errorf("音频上下文初始化失败: %w", err)
+    }
+
+    dec, err := mp3.NewDecoder(r)
+    if err != nil {
+        r.Close()
+        return fmt.Errorf("MP3 解码失败: %w", err)
+    }
+    defer r.Close()
+
+    player := otoCtx.NewPlayer(dec)
+    defer player.Close()
+
+    player.Play()
+
+    done := make(chan struct{})
+    go func() {
+        for player.IsPlaying() {
+            time.Sleep(time.Millisecond)
+        }
+        close(done)
+    }()
+
+    select {
+    case <-done:
+        return nil
+    case <-ctx.Done():
+        return ctx.Err()
+    }
+}
+```
+
+### 3.3 BGM 循环播放(非阻塞)
+
+**PlayMP3Loop:** 循环播放 MP3,立即返回 player 和清理函数
+
+**资源管理:** 使用 atomic.Bool 和 sync.WaitGroup 控制 goroutine 生命周期,确保安全退出
+
+```go
+import "sync/atomic"
+
+func PlayMP3Loop(r io.ReadCloser) (*oto.Player, func() error, error) {
+    otoCtx, err := initContext()
+    if err != nil {
+        r.Close()
+        return nil, func() error { return nil }, err
+    }
+
+    dec, err := mp3.NewDecoder(r)
+    if err != nil {
+        r.Close()
+        return nil, func() error { return nil }, err
+    }
+
+    player := otoCtx.NewPlayer(dec)
+
+    // 使用 atomic.Bool 和 WaitGroup 控制 goroutine 生命周期
+    playing := atomic.Bool{}
+    playing.Store(true)
+    var wg sync.WaitGroup
+    wg.Add(1)
+
+    go func() {
+        defer wg.Done()
+        for playing.Load() {
+            player.Play()
+            for playing.Load() && player.IsPlaying() {
+                time.Sleep(time.Millisecond)
+            }
+            if playing.Load() {
+                player.Seek(0)
+            }
+        }
+    }()
+
+    cleanup := func() error {
+        // 1. 通知 goroutine 退出
+        playing.Store(false)
+
+        // 2. 等待 goroutine 完全退出
+        wg.Wait()
+
+        // 3. 按照 oto 最佳实践的顺序释放资源
+        player.Close()
+        return r.Close()
+    }
+
+    return player, cleanup, nil
+}
+```
+
+**设计说明:**
+- ✅ 使用 `atomic.Bool` 明确控制 goroutine 生命周期
+- ✅ 使用 `sync.WaitGroup` 明确等待 goroutine 退出
+- ✅ goroutine 在每毫秒都检查退出条件,确保快速响应
+- ✅ 清理函数先通知退出,等待 goroutine 完全停止,再释放资源
+- ✅ 符合 oto 官方要求:"Do NOT close [reader] before you finish playing"
+- ✅ 无竞态条件,无资源泄漏,并发安全
+
+### 3.4 业务层使用示例
+
+**场景1: TTS 播放 (pkg/tts/aliyun.go)**
+
+改动前(beep):
+```go
+audio.PlayWav(ctx, buf)
+```
+
+改动后(oto):
+```go
+err := audio.PlayWav(ctx, buf)
+if err != nil && !errors.Is(err, context.Canceled) {
+    zap.S().Errorf("TTS 播放失败: %v", err)
+}
+```
+
+**场景2: BGM 播放 (internal/middleware/bgm.go)**
+
+改动前(beep):
+```go
+ctrl, closer, e := audio.PlayBgmMP3(bgm)
+defer closer()
+<-a
+speaker.Lock()
+ctrl.Streamer = nil
+speaker.Unlock()
+```
+
+改动后(oto):
+```go
+player, cleanup, err := audio.PlayMP3Loop(bgm)
+if err != nil {
+    zap.S().Errorf("BGM 启动失败: %v", err)
+    return err
+}
+defer cleanup()  // ✅ 一次性清理所有资源,顺序正确
+
+<-a
+// cleanup() 会先 player.Close() 停止播放,再 r.Close() 清理 reader
+```
+
+## 4. API 设计
+
+### 4.1 公开接口
+
+```go
+package audio
+
+import (
+    "context"
+    "io"
+    "sync"
+    "sync/atomic"
+    "time"
+
+    "github.com/ebitengine/oto/v3"
+    "github.com/go-audio/wav"
+    "github.com/hajimehoshi/go-mp3"
+)
+
+// PlayMP3 播放 MP3 文件(阻塞),直到完成或 context 取消
+func PlayMP3(ctx context.Context, r io.ReadCloser) error
+
+// PlayWav 播放 WAV 文件(阻塞),直到完成或 context 取消
+func PlayWav(ctx context.Context, r io.ReadCloser) error
+
+// PlayMP3Loop 循环播放 MP3(非阻塞)
+// 返回 player 和清理函数,调用者负责 defer cleanup()
+func PlayMP3Loop(r io.ReadCloser) (*oto.Player, func() error, error)
+```
+
+### 4.2 功能覆盖
+
+| 当前功能 | 当前 API | oto API | 说明 |
+|---------|---------|---------|------|
+| TTS 播放 | `PlayWav(ctx, r)` | `PlayWav(ctx, r)` | 新增 error 返回 |
+| BGM 循环 | `PlayBgmMP3(r, ...)` | `PlayMP3Loop(r)` | 返回 player 和清理函数 |
+
+## 5. 错误处理和资源管理
+
+### 5.1 错误处理策略
+
+- ✅ 一次性播放: 忽略 `context.Canceled`,记录其他错误
+- ✅ BGM 播放: 所有错误都需要返回(影响启动)
+- ✅ 统一使用 `fmt.Errorf` 包装错误信息
+
+### 5.2 资源管理
+
+**一次性播放:**
+- ✅ `defer r.Close()` 确保资源释放
+- ✅ `defer player.Close()` 确保播放器释放
+- ✅ 函数内部完整管理资源生命周期
+
+**BGM 循环播放:**
+- ✅ 返回清理函数 `func() error`,内部保证正确的释放顺序
+- ✅ 先 `player.Close()` 停止播放,再 `r.Close()` 清理 reader
+- ✅ 符合 oto 官方要求:"Do NOT close [reader] before you finish playing"
+- ✅ 业务层 `defer cleanup()` 一次性清理所有资源
+- ✅ 责任边界清晰,资源管理可靠
+
+### 5.3 并发安全
+
+- ✅ `sync.Once` 保证全局 Context 线程安全
+- ✅ 每个 Player 独立,无共享状态
+- ✅ `player.Close()` 是线程安全的
+- ✅ `atomic.Bool` 控制 goroutine 生命周期,无竞态条件
+- ✅ `sync.WaitGroup` 明确等待 goroutine 退出,确保资源安全释放
+
+## 6. 测试策略
+
+### 6.1 单元测试
+
+- TestInitContext - 测试音频上下文初始化
+- TestPlayMP3 - 测试 MP3 播放
+- TestPlayWav - 测试 WAV 播放
+- TestPlayContextCancellation - 测试 Context 取消
+- TestPlayMP3LoopStop - 测试 BGM 停止
+- TestConcurrentPlay - 测试并发播放
+
+### 6.2 测试数据
+
+```
+pkg/audio/testdata/
+├── test.mp3
+├── test.wav
+└── corrupt.mp3
+```
+
+## 7. 实施计划
+
+### 7.1 实施步骤
+
+1. **添加依赖**
+   ```bash
+   go get github.com/go-audio/wav
+   ```
+
+2. **实现核心组件**
+   - initContext()
+   - PlayWav()
+   - PlayMP3()
+   - PlayMP3Loop()
+
+3. **更新业务层**
+   - pkg/tts/aliyun.go
+   - internal/middleware/bgm.go
+   - internal/routes/standby/audio.go
+
+4. **移除旧依赖**
+   ```bash
+   go mod tidy
+   ```
+
+5. **测试**
+   - 单元测试
+   - 集成测试
+
+### 7.2 风险评估
+
+**低风险:**
+- API 简单清晰
+- 依赖成熟稳定
+- 业务层改动最小
+
+**需验证:**
+- 树莓派 ARM64 平台兼容性
+- 循环播放性能
+- 并发播放稳定性
+
+## 8. 验收标准
+
+- ✅ 所有单元测试通过
+- ✅ 实际播放测试通过
+- ✅ BGM 循环播放正常
+- ✅ Context 取消机制正常
+- ✅ 无资源泄漏
+- ✅ 树莓派平台运行正常