消费模块语音提示与读卡器状态镜像变更记录

变更信息

1. 变更结果

• 新增面向就餐人员的“用户动作 + 业务结果”语音策略。
• 新增语音会话去重、优先级抢占和播放器生命周期控制。
• 支付异常不再笼统处理为“支付失败”，而是区分首次读卡失败、确定未扣款的余额不足和扣款结果待确认。
• 接口 C 上报失败不否定已经确认的本地扣款结果，对就餐人员仍提示支付成功，后台继续补传。
• 零金额订单使用独立核验语义，不播放支付或扣款文案。
• 读卡器异常红字从页面右侧移动到左侧水平镜像位置，纵向位置、样式和显示逻辑不变。

2. 代码结构

Activity 不直接引用新语音资源 ID，也不根据写卡回调自行判断应播报的最终结果。

3. 语音资源

新文件均放入现有目录 app/src/main/res/raw/：

3.1 声线与参数

• 参考对象：消费页正在使用的 please_place_card.wav。
• 声线：macOS 中文普通话女声 Tingting。
• 合成语速参数：175。
• 2026-08-29 真机试听前调整：十条 consumption_*.wav 在不改变音调的前提下统一加速为原文件的 1.2 倍。
• 输出格式：PCM signed 16-bit little-endian、22050Hz、单声道 WAV。
• 新文件平均音量约 -18.1dB 至 -19.2dB，峰值约 -2.6dB 至 -4.2dB，无削波。
• 播放控制器继续沿用原消费语音将媒体音量调整为最大值的行为，避免更换播放器后现场声音明显变小。

3.2 同源复现证据

使用相同声线、语速和转换参数重新合成参考句“请放卡片进行支付”，其 PCM SHA-256 与现有 please_place_card.wav 完全一致：

016128497cb7cf4c75abef470d5b5427e417f3dc8a816a81b4cdb599ebc93ec6

因此本次新文件的声线、语调风格和原始音量处理链路与当前消费语音一致；交付语速按真机试听反馈统一调整为原文件的 1.2 倍。

3.3 本次语速调整验证

• 调整范围：仅今天 11:54 新增的十条 consumption_*.wav，未修改 please_place_card.wav 和 please_swipe_card.mp3。
• 处理方式：使用保留音调的时间伸缩，目标播放速度为当前文件的 1.2 倍。
• 实测时长换算范围：1.1983 至 1.2028 倍，差异来自音频帧边界。
• 格式复核：十条文件均保持 pcm_s16le、22050Hz、单声道 WAV。

4. 播放与安全规则

• 每个餐盘会话的等待放卡、处理中和最终结果按稳定业务键去重，页面重绘不会重复播报。
• 高优先级安全提示可以中断低优先级动作提示；低优先级提示不能覆盖支付结果待确认。
• 新餐盘会话开始时清除上一会话去重状态和残留播放器。
• 零金额读卡可重试，每次真实读卡失败使用独立尝试序号，避免后续失败被错误去重。
• 读卡器不可用只在等待放卡时播报；同一连续异常只播一次，恢复后再次断开可以重新提示。
• 语音开关关闭时不播放，但不影响页面状态和交易流程。

5. 交易失败分类

余额不足只在“没有任何已完成扣款”时归类为确定失败；部分扣款后出现同名错误仍保持结果待确认。

6. 读卡器提示布局

consumption_reader_status 调整为：

android:layout_alignParentStart="true"
android:layout_marginStart="@dimen/common_title_bar_horizontal_margin"

移除了对应 End 属性。仍位于标题状态视图下方，继续使用原顶部外边距、字号、颜色和 gone 初始状态；业务代码仍只有 Tone.ERROR 时显示。

7. 自动化验证

新增测试

• ConsumptionVoicePolicyTest：事件映射、优先级和空事件保护。
• ConsumptionVoicePlaybackGateTest：会话去重、抢占、低优先级跳过、播放失败重试和会话复位。
• ConsumptionVoiceOutcomeClassifierTest：首次读卡失败、未扣款余额不足、普通扣款异常和部分扣款后余额不足。

执行结果

• :app:testDebugUnitTest：通过，共 129 个测试，0 failure、0 error、0 skipped。
• :app:assembleDebug：通过。
• Debug APK：app/build/outputs/apk/debug/app-debug.apk，约 64MB。
• git diff --check：通过，无空白错误。
• 静态检查：十个控制器资源引用与十个 WAV 文件一一对应；Activity 无新语音资源直连；未引入运行时 TTS。

构建继续使用项目兼容的 Amazon Corretto JDK 8。日志中保留旧 Android 构建链对 core-lambda-stubs.jar 主版本的既有警告，不影响构建成功。

8. 真机待验

• 食堂环境噪声下的实际音量、语速和可理解性。
• 连续订单的播报顺序、抢占和无串音。
• 真实余额不足、首次读卡失败、扣款后复读失败和接口 C 上报失败。
• USB 读卡器拔插和权限拒绝时的连续异常去重。
• 目标屏幕上读卡器红字的左侧镜像位置。

9. Git 边界

本次只执行只读 Git 状态、差异和空白检查；未暂存、提交、推送或执行其他 Git 写操作。