读卡器连接异常重新初始化变更记录

后续修正：本记录中的异常触发范围已由读卡器重新初始化提示触发范围修正记录收窄；当前规则仅针对成功初始化后的连接异常。

• 日期：2026-09-13
• 项目：ZhctTrayBindingMachine

结论：消费页在读卡器设备未找到、USB 权限拒绝、连接断开或致命异常时弹出确认框；用户点击“确定”后释放旧连接并重新执行设备发现、权限确认、连接及协议初始化。

Compact Use Case

• Use Case ID / 状态 / DoR：UC-READER-REINIT-001 / Done / READY
• 角色、触发与目标：操作人员遇到读卡器连接异常时，可在当前消费页直接确认重新初始化，无需重启应用。
• In Scope / Out of Scope：新增异常确认框、确认后的完整重新初始化、防重复门禁、日志及回归测试；不修改一卡通协议、订单内容、扣款规则和服务器接口。
• 主流程：读卡器连接异常后展示“读卡器连接异常，是否重新初始化？”；点击确定后显示初始化中，关闭旧连接，再重新发现设备并建立连接，连接阶段继续执行协议初始化。
• 取消流程：点击取消只关闭确认框并保留当前错误状态；后续再次发生连接异常时仍可重新提示。
• 边界或异常/恢复：连续异常只展示一个确认框；一次确认只发起一次重试；连接流程恢复后清除旧提示；页面离开或销毁时主动关闭提示框。
• 订单保护：重新初始化不清空当前待处理订单，且硬件交易进行中不接受重新初始化，避免中途打断扣款。
• 验收标准：四类连接异常均能触发提示；确定后走完整初始化；取消不重试；重复回调不叠加弹框；单元测试和 Debug 构建通过。
• 待确认项：需要在现场通过拔插读卡器、无设备和 USB 权限拒绝场景完成真机交互与硬件恢复验收。

实现

• 新增 ReaderInitializationRetryGate，集中维护提示框和重试状态，防止异常回调密集到达时重复弹框或重复初始化。
• ConsumptionActivity 在设备未找到、USB 权限拒绝、断开和读卡器错误回调中展示确认框。
• 用户确定后调用 ConsumptionCardSearchManager.reinitialize()；页面更新为“读卡器初始化中”，并记录 CARD_READER_REINITIALIZE 和 CONSUMPTION_READER_REINITIALIZE 日志。
• ConsumptionCardSearchManager 串行停止当前会话并断开旧连接，再重新执行设备发现、权限确认和连接；NewcapecUsbCardReader.connect() 内继续调用协议 initialize()，因此属于完整重新初始化。
• 页面进入连接或寻卡状态后关闭已经失效的提示框；onStop() 和 onDestroy() 同样负责清理提示框。

测试与验证

• TDD RED：JDK 8 下先添加门禁测试，因 ReaderInitializationRetryGate 尚不存在而编译失败。
• 定向测试：ReaderInitializationRetryGateTest 4 个测试通过，覆盖重复异常、重复确认、取消后再次提示及恢复后清理。
• 完整单元测试：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:testDebugUnitTest --rerun-tasks，199 个测试，0 failure、0 error、0 skipped。
• Debug 构建：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:assembleDebug，构建成功。
• APK：app/build/outputs/apk/debug/app-debug.apk，大小 67186843 字节，SHA-256 0070e8c4fb8e36d1095a8a9ddca9be529b4721be0832f35ebabe5135f19efa8b。
• 本次未安装 APK、未操作现场读卡器、未触发真实订单或扣款。

Git 边界

本次未执行暂存、提交、推送、拉取、分支切换或其他 Git 写操作。