StandAPP/docs/superpowers/specs/2026-07-06-temp-call-voice-alert-design.md

临时呼叫页面语音提示与确认功能设计规约 (Design Spec)

1. 需求概述

在 TempCallActivity 弹出页面（临时呼叫页面）时，需要播放一段本地语音提示。

• 语音播报文本："您有一条拉动，请注意确认"。
• 播报循环规则：若用户不操作，默认播放并重复 3 次。
• 交互设计：
  • 页面中央的信息卡片中新增一个“确认”按钮。
  • 用户点击“确认”按钮时，能够立即静音/停止当前正在播放的语音，且该按钮在静音后隐藏。
  • 点击“确认”按钮时仅关闭语音播放，暂时不需要关闭页面。

2. 方案设计

2.1 语音资源准备

• 文件名：pull_alert.wav
• 保存路径：app/src/main/res/raw/pull_alert.wav（若没有 raw 文件夹，将自动创建）
• 生成方式：使用 Python 脚本调用 Edge TTS 等免费 TTS 接口，在线合成带有“您有一条拉动，请注意确认”文本的高质量 WAV 音频，并自动保存到对应目录下。

2.2 布局修改

• 目标文件：app/src/main/res/layout/activity_temp_call.xml
• 修改位置：在包含 tv_talk_status 的内部 LinearLayout 容器下方，添加“确认”按钮。
• 按钮样式：
  • 文字："确认"
  • 默认可见性：android:visibility="gone"（开始播放时显示，停止播放/确认后隐藏）
  • 背景：复用现有 @drawable/btn_minimize_bg。

        <!-- 用于确认并静音语音的按钮 -->
        <Button
            android:id="@+id/btn_confirm_alert"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_marginTop="16dp"
            android:background="@drawable/btn_minimize_bg"
            android:text="确认"
            android:textColor="#FFFFFF"
            android:textSize="14sp"
            android:visibility="gone" />

2.3 业务逻辑实现

• 目标文件：app/src/main/java/com/stand/standapp/TempCallActivity.kt
• 主要逻辑：
  1. 定义 MediaPlayer 实例 private var alertPlayer: MediaPlayer? = null 及播放计数器 private var alertPlayCount = 0。
  2. 实现播放方法 private fun startVoiceAlert()：
     • 如果 alertPlayer 尚未初始化，利用 MediaPlayer.create(this, R.raw.pull_alert) 初始化。
     • 显示“确认”按钮：btnConfirmAlert.visibility = View.VISIBLE。
     • 监听播放完成事件：

       alertPlayer?.setOnCompletionListener {
           alertPlayCount++
           if (alertPlayCount < 3) {
               alertPlayer?.start()
           } else {
               stopVoiceAlert()
           }
       }
       

     • 开始播放并设置 alertPlayCount = 0。
  3. 实现停止方法 private fun stopVoiceAlert()：
     • 安全释放 MediaPlayer 资源：

       alertPlayer?.let { player ->
           try {
               if (player.isPlaying) {
                   player.stop()
               }
           } catch (e: Exception) {
               // 忽略错误
           } finally {
               player.release()
           }
       }
       alertPlayer = null
       

     • 隐藏“确认”按钮：btnConfirmAlert.visibility = View.GONE。
  4. 设置“确认”按钮的点击事件：
     • 点击时调用 stopVoiceAlert()。
  5. 页面销毁生命周期：
     • 在 onDestroy() 中，必须调用 stopVoiceAlert() 以防止内存泄漏和页面销毁后后台仍在播放的情况。

3. 测试与自审规范

• 测试用例 1：启动临时呼叫页面，验证语音提示是否以正常音量播放，且重复播放 3 次后自动停止，同时“确认”按钮自动隐藏。
• 测试用例 2：语音播放期间点击“确认”按钮，验证语音是否立刻停止播放，且“确认”按钮是否立即隐藏。
• 测试用例 3：语音播放期间直接关闭或最小化页面，验证后台音乐播放器是否正确释放，不存在背景音残留。