支付成功弹框余额显示开关设计

设计日期：2026-09-01

项目仓库：/Users/liang/AndroidStudioProjects/CusumptionMachine

当前实施分支：fix_pay_by_face

背景与现状

消费机当前有两种支付成功弹框：基础版 ShowPaymentSuccessPop 和营养增强版 ShowPaymentSuccessWithNutritionPop。基础版同时被普通支付、国信刷脸支付、记账成功和订单核验成功场景复用；营养增强版由 MainActivity 在营养展示开关开启时使用。

两个弹框目前仅根据余额字符串是否为空决定余额行是否显示，设置页没有统一控制项。业务需要在“支付设置”中增加开关，让管理员能够统一控制支付成功结果中是否展示账户余额，且未配置设备继续保持当前“显示余额”的行为。

目标

• 在“设置 > 支付设置”中增加“支付成功显示余额”开关。
• 开关默认开启，保证升级后未配置设备继续显示非空余额。
• 关闭后，基础版和营养增强版支付成功弹框都隐藏余额行。
• 订单核验成功等复用基础版弹框的场景统一遵循该开关。
• 余额为空时，无论开关是否开启都保持隐藏。
• 修改设置后无需重启，下一次弹框展示立即生效。

方案选择

采用“弹框读取统一偏好配置”的方案：支付设置页只负责保存开关，两个弹框在绑定余额数据时读取配置并决定余额视图可见性。

该方案不修改各 Activity 的构造方法或调用参数，能够覆盖当前全部调用入口，也能让后续新增调用默认遵循同一规则。未采用由各 Activity 传入布尔值或在每个调用点手动隐藏的方案，因为这两种方式改动分散，容易遗漏订单核验、记账或后续新增页面。

界面设计

在 FragmentPayment 对应的支付设置页面中，紧接“支付结果弹框显示时长”增加一行设置项：

• 标题：支付成功显示余额。
• 控件：复用项目现有 SwitchButton。
• 默认状态：开启。
• 开启：支付成功弹框在余额非空时显示余额。
• 关闭：支付成功弹框隐藏余额行。

设置项文案使用字符串资源，开关尺寸复用资源值，不在布局和业务代码中新增可避免的硬编码。

配置设计

在 Constants 中新增职责明确的配置键和默认值：

• PAYMENT_SUCCESS_BALANCE_VISIBLE：本地偏好键。
• PAYMENT_SUCCESS_BALANCE_VISIBLE_DEFAULT：默认值 true。

FragmentPayment 进入页面时读取配置初始化开关；用户切换时通过 PreferenceUtils.putBoolean(...) 立即持久化。

弹框处理

基础版弹框

ShowPaymentSuccessPop 增加统一的余额绑定方法，供 setPaymentResultInfo(...) 和 setOrderVerifyResultInfo(...) 调用。余额行显示条件为：

配置开启 && 余额字符串非空

条件不满足时将 show_payment_success_pop_show_balance_tv 设置为 View.GONE，满足时显示并设置余额文本。

营养增强版弹框

ShowPaymentSuccessWithNutritionPop.applyPaymentInfo(...) 使用相同判断规则控制 pay_success_show_balance_tv。其他支付信息、营养数据、动画和自动关闭逻辑保持不变。

数据流

1. 管理员进入“支付设置”。
2. FragmentPayment 读取余额显示配置，未配置时使用默认值 true。
3. 管理员切换开关，配置立即写入本地偏好。
4. 下一次支付成功或订单核验成功弹框绑定支付结果时读取最新配置。
5. 配置关闭时隐藏余额行；配置开启且余额非空时显示余额。

异常与兼容处理

• 旧版本升级且没有保存过配置：默认显示余额，与原行为一致。
• 余额字段为空或为 null：继续隐藏余额，不显示空占位。
• 记账成功场景通常不返回余额：继续按空余额规则隐藏。
• 修改开关时已有弹框不动态刷新；下一次弹框展示使用新配置。
• 不改变支付接口、支付流程、订单保存、声音提示、弹框时长和自动关闭回调。
• 不改变客显副屏 HomeSecondPresentation 的独立支付结果界面。

测试与验收

构建检查

• 执行 app 模块 Debug Java 编译或 Debug APK 构建。
• 执行 git diff --check，确认没有空白符错误。
• 检查新增及修改文本文件为 UTF-8 无 BOM，中文为简体中文。

功能验收

• 首次进入支付设置时，“支付成功显示余额”默认开启。
• 关闭开关并重新进入设置页，开关仍保持关闭。
• 基础版支付成功弹框在开关关闭时不显示余额。
• 营养增强版支付成功弹框在开关关闭时不显示余额。
• 订单核验成功弹框在开关关闭时不显示余额。
• 重新开启开关后，上述弹框在余额非空时恢复显示余额。
• 开关开启但余额为空时，余额行仍隐藏。

交付边界

• 本次仅增加支付成功结果的余额显示设置。
• 不调整支付成功弹框的其他字段和布局结构。
• 不修改各支付页面现有调用方式。
• 不执行设备安装、Git 暂存、提交或推送，除非用户后续明确要求。