扫码支付 HTTP 超时时间配置设计

设计日期：2026-09-16

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

当前实施分支：cqhw_logo

背景与现状

当前消费机 HTTP 客户端统一使用 5 秒连接、读取和写入超时。扫码成功后的支付请求也复用该全局客户端，因此服务端处理付款码超过 5 秒未返回数据时，会进入“请求超时”失败流程。

业务需要将扫码支付等待接口返回的时间改为可配置项：默认 30 秒，管理员可在“支付设置”中输入 1～100 的整数秒数。该配置只影响当前可达页面中的扫码支付 HTTP 读取超时，不扩大到其他接口、刷卡支付、人脸支付、扫码弹框等待或 MQTT 支付。

目标

• 在“设置 > 支付设置”增加“扫码支付超时时间”设置项。
• 默认值为 30 秒，允许输入 1～100 的整数。
• 修改后从下一笔扫码支付开始生效，应用重启后仍保留。
• 扫码支付的连接和写入超时继续保持 5 秒，仅等待服务端响应的读取超时使用配置值。
• 其他 HTTP 接口、刷卡支付和人脸支付继续使用全局 5 秒超时。
• 保留当前“请求超时”错误处理、支付失败提示和订单处理逻辑。

范围

本次覆盖以下 5 个当前可达支付页面：

• MainActivity
• QuotaActivity
• QuotaNoKeyboardActivity
• FreeActivity
• FreeNoKeyboardActivity

明确排除：

• NewQuotaActivity
• 仅由 NewQuotaActivity 使用的 PaymentManager
• 扫码弹框 5/10 秒等待时间
• MQTT 支付 5 秒倒计时
• 其他业务接口超时配置

方案选择

采用“扫码支付专用可配置读取超时”方案。

不直接修改 CustomApplication.TIME_OUT，因为该值被全部 Retrofit 请求共用，改为 30 秒会扩大登录、菜品、同步等接口的等待时间。扫码支付请求将在发起时基于现有 OkHttpClient 创建专用客户端，只覆盖 readTimeout；connectTimeout 和 writeTimeout 继续继承全局 5 秒。

未采用自定义请求头配合拦截器动态切换超时的方案，因为隐藏请求头会引入网络层约定，且当前项目使用较旧的 OkHttp/Retrofit 版本，专用客户端方案更直接、可读且便于测试。

配置设计

新增职责单一的扫码支付超时配置类，集中维护本地偏好键、默认值 30 秒、最小值 1 秒、最大值 100 秒、输入校验、配置读写和异常回退。

配置值使用整数秒保存，不在 Activity、Fragment、弹框或网络代码中重复硬编码边界和默认值。

设置界面设计

在 FragmentPayment 对应的“支付设置”页面增加“扫码支付超时时间”设置行，右侧以“30秒”等格式显示当前值，点击后打开数字输入弹框。

• 打开时显示当前配置并全选。
• 键盘类型为数字。
• 确认时校验非空、整数且位于 1～100。
• 失败时保持弹框打开并提示“请输入1～100之间的整数”。
• 成功后由 FragmentPayment 持久化并刷新当前值。
• 取消时不修改原配置。

网络层设计

RetrofitClient 增加创建扫码支付专用 API 实例的能力：

1. 读取当前基础地址。
2. 基于 CustomApplication.mOkHttpClient.newBuilder() 创建客户端。
3. 仅把 readTimeout 设置为扫码支付配置值。
4. 保持原客户端的连接池、拦截器、证书和其他网络行为。
5. 使用专用客户端创建本次扫码支付所需的 Retrofit/API 实例。

RetrofitRequest.orderPayment(...) 增加支付类型参数：paymentType == 2 时使用专用 API 实例，其他支付类型继续使用现有全局 API 实例。5 个支付页面传入当前支付类型，避免在页面中复制客户端创建逻辑。

数据流

1. 管理员进入“支付设置”，页面读取配置；未配置或异常时显示 30 秒。
2. 管理员输入 1～100 的整数并确认，配置写入本地偏好。
3. 用户完成扫码，支付页面以 paymentType == 2 发起 HTTP 支付。
4. 网络层读取最新配置并创建本次请求的专用客户端。
5. 连接和写入阶段继续使用 5 秒，读取响应阶段使用配置值。
6. 超时后继续沿用现有“请求超时”处理。

异常与兼容处理

• 旧版本升级且没有配置记录：使用默认 30 秒。
• 本地配置越界：读取时回退 30 秒。
• 输入为空、非整数、0 或大于 100：不保存并显示校验提示。
• 修改设置时已有支付请求保持启动时的超时值，下一笔使用新值。
• 网络断开、连接失败、业务错误码和余额不足继续使用现有处理。
• HTTP 读取超时继续映射为 REQUEST_TIMEOUT 和“请求超时”。
• 不调整支付失败遮罩层显示时长。

测试与验收

自动测试

• 未保存配置时返回 30。
• 1 和 100 通过校验并可保存。
• 0、101 和其他越界值不通过校验。
• 非扫码支付继续使用全局客户端。
• 扫码支付读取超时等于配置值，连接和写入超时仍为 5 秒。
• 专用客户端不改变全局客户端超时。

构建检查

• 执行 app 模块 Debug Java 编译或 Debug APK 构建。
• 执行相关单元测试和 git diff --check。
• 检查文本文件为 UTF-8 无 BOM，中文为简体中文。

功能验收

• 首次进入支付设置显示“30秒”。
• 输入 1 或 100 后保存成功，重新进入仍显示保存值。
• 非法值不覆盖原配置。
• 设置 30 秒后，扫码支付不在原 5 秒读取超时点提前失败。
• 超过设置值仍未收到响应时显示“请求超时”。
• 刷卡、人脸和其他接口行为保持不变。
• NewQuotaActivity 和 PaymentManager 无代码改动。

交付边界

• 本次只增加当前 5 个可达支付页面的扫码支付 HTTP 读取超时配置。
• 不修复 QrcodeScanPop 倒计时残留等其他扫码问题。
• 不调整支付页面结构、扫码硬件适配、接口参数和订单保存规则。
• 不执行 Git 暂存、提交或推送，除非用户后续明确要求。