消费模块语音提示与读卡器状态布局设计

文档信息

1. 背景与结论

消费流程当前主要依赖页面文案提示，仅有“请放卡片进行支付”语音。就餐人员在看向餐盘、卡片或读卡区时，可能错过支付状态变化；但如果播报首次读卡成功、写卡成功等技术阶段，又会造成提示密集、术语难懂，并可能让用户误以为交易已经完成。

最终采用“用户动作 + 业务结果”语音策略：只在就餐人员需要执行动作、获知最终结果或规避重复扣款风险时播报。首次读卡成功、写卡成功等内部阶段不单独播报；任何已经尝试扣款但无法确认最终结果的异常，都不能简单播报“支付失败”。

读卡器异常文字只做水平镜像：从屏幕右侧移到左侧对应位置，上下位置、字号、颜色、外边距数值和显示条件均保持不变。

2. 目标与范围

2.1 目标

• 让就餐人员无需持续盯住屏幕，也能正确完成放卡、等待和取卡动作。
• 明确区分支付成功、未扣款失败和扣款结果不确定，避免重复刷卡。
• 避免播报读卡、写卡等内部技术阶段。
• 防止同一交易状态因轮询、页面刷新或回调重复而连续播报。
• 保持语音与页面业务文案的语义一致。
• 将读卡器异常提示移动到当前右侧位置的左侧镜像位置。

2.2 范围内

• 正金额订单的等待放卡、支付处理中和最终结果语音。
• 零金额订单的放卡核验和最终结果语音。
• 无待支付订单、读卡失败、交易结果待确认、读卡器不可用等异常语音。
• 语音开关、去重、优先级和播放生命周期。
• 读卡器异常提示的水平镜像布局。
• 语音策略单元测试、页面布局检查和真机验收规则。

2.3 范围外

• 不改变消费交易协议、扣款顺序和后台上报规则。
• 不向就餐人员播报首次读卡成功、写卡成功等技术阶段。
• 不新增联网 TTS；继续使用本地语音资源和现有语音开关。
• 不改变读卡器连接状态的判定逻辑和红字显示条件。
• 不调整读卡器异常文字的纵向位置、样式或内容。

3. 方案对比与选型

4. 语音提示清单

4.1 必须播报

4.2 条件播报

4.3 不单独播报

5. 交易结果语义

消费语音不能只使用“成功/失败”二分类，必须使用以下业务结果：

“结果不确定”优先于一般失败提示。此状态必须同时在页面展示“请勿重复支付”类警示，并禁止自动重新发起同一笔扣款。

6. 播放策略

6.1 触发原则

• Activity 只上报“等待卡片、开始支付、支付成功、未扣款失败、结果不确定”等业务事件，不直接根据读卡/写卡回调拼接语音。
• 页面文案和语音共用同一业务语义映射，避免页面显示成功而语音提示失败。
• 语音开关关闭时不播放，但不得改变状态机和页面结果。
• 页面重绘、生命周期回调、硬件轮询和相同状态重复回调不得触发重复播报。

6.2 去重范围

• 等待放卡、开始支付和最终结果按“餐盘订单会话 + 交易尝试”去重。
• 无待支付订单按“餐盘查询会话”去重。
• 读卡器不可用按“连续异常区间”去重；恢复连接后再次断开可重新提示一次。
• 新订单、新交易尝试或新的连续硬件异常区间会建立新的去重范围。

6.3 优先级

1. 支付结果待确认等防重复扣款安全提示。
2. 确定失败和余额不足等终止结果。
3. 支付成功或核验成功。
4. 正在支付、等待放卡等动作提示。
5. 读卡器不可用等硬件建议。

高优先级事件到达时可以停止尚未完成的低优先级提示；同级或低级重复事件不叠加播放。一个最终结果确定后，本次交易不再播放等待或处理中提示。

7. 组件职责设计

语音资源使用具名资源和枚举集中管理，禁止在 Activity 中散落资源 ID、优先级数字或提示文案。类和非显然的交易安全判断应增加责任及原因注释。

8. 本地语音资源

• 继续使用项目现有本地音频播放能力和语音开关，不依赖网络。
• 新增语音文件采用统一命名，例如 consumption_payment_success、consumption_payment_unknown，禁止用 audio1 等无语义名称。
• 录音文案以本设计为唯一业务基准；文件格式、采样率、声道和响度与现有可正常播放资源保持一致。
• 实施时先复核现有音频是否可复用；文案语义不完全一致时不得勉强复用。
• 语音应完整、自然、无静音长尾；真机播放不得截断下一条高优先级提示。

9. 读卡器异常提示左侧镜像

现有 consumption_reader_status 位于页面右侧。布局只做水平镜像：

此调整不新增绝对坐标或重复尺寸，继续复用现有 dimen，以保证不同分辨率下仍是相对屏幕边缘的镜像位置。

10. 状态映射

11. 验收标准

12. 测试策略

12.1 自动化测试

• ConsumptionVoicePolicyTest：覆盖所有业务结果到语音类型的映射。
• ConsumptionVoiceControllerTest：覆盖语音开关、同状态去重、连续异常区间、高优先级抢占和最终状态封口。
• 交易结果分类测试：重点覆盖“首次读卡失败”“扣款后复读失败”“卡片不一致”“上报待补传”。
• 正金额与零金额测试：验证零金额流程不会映射到任何支付语音。
• 布局静态检查：验证使用 layout_alignParentStart 和 layout_marginStart，且不再使用对应 End 属性。

12.2 构建与静态检查

• 执行消费模块相关单元测试和完整 testDebugUnitTest。
• 执行 assembleDebug。
• 检查新增资源命名、未引用资源、文案硬编码和重复优先级数字。
• 检查语音和页面最终结果由同一业务分类驱动。

12.3 真机验收

• 验证环境噪声下的音量、语速和可理解性。
• 验证放卡后提示不会让用户提前取卡。
• 验证连续订单不会漏播或串播上一笔结果。
• 验证读卡器拔插、USB 权限失败和重连时只提示一次连续异常。
• 验证支付结果待确认时页面和语音都明确禁止重复刷卡。
• 验证读卡器异常文字在不同设备分辨率下保持左侧镜像位置。

13. 风险与控制

14. 设计结论

• 采用“用户动作 + 业务结果”语音方案。
• 必须把支付异常拆为“确定未扣款”和“结果不确定”，禁止笼统播报支付失败。
• 首次读卡成功、写卡成功和写卡失败不直接面向就餐人员播报。
• 正金额使用支付语义，零金额使用核验语义。
• 语音由集中策略映射并按会话去重，安全提示拥有最高优先级。
• 读卡器异常提示从右侧移动到左侧镜像位置，其他布局和显示逻辑不变。
• 本设计已由用户确认；完成设计文档复核后，再生成代码实施计划。