协议初始化失败再次提示变更记录

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

结论：用户确认重新初始化后若发生 PROTOCOL_ERROR，页面会再次提示“读卡器初始化失败，是否重新初始化？”；再次确认后重新执行完整初始化，成功或取消后才结束本轮重试上下文。

Compact Use Case

• Use Case ID / 状态 / DoR：UC-READER-REINIT-003 / Done / READY
• 角色、触发与目标：操作人员确认处理连接异常后，如果重新初始化因协议通道异常等 PROTOCOL_ERROR 失败，可继续在当前页面确认再次初始化，无需切换页面恢复。
• In Scope / Out of Scope：新增确认重试后的协议失败识别、再次弹框、专用文案和重试状态清理；不把普通读卡阶段的协议错误归类为连接异常，不修改 HID 协议和消费规则。
• 主流程：连接异常弹框确认后记录重试上下文；重新初始化出现 PROTOCOL_ERROR 时提示“读卡器初始化失败，是否重新初始化？”；点击确定再次执行完整初始化。
• 结束流程：初始化成功或用户取消后结束重试上下文；页面离开或重试请求未被管理器接受时也清理上下文。
• 边界或异常/恢复：同一次错误只展示一个弹框；每次确定只启动一次初始化；连续协议初始化失败可以逐次询问，但不会自动无限重试。
• 非触发场景：首次启动直接发生 PROTOCOL_ERROR、普通读卡过程协议错误、设备未找到、权限拒绝、卡片和业务错误不进入本规则。
• 验收标准：连接异常确认后发生协议初始化失败会再次弹框；再次确认可继续初始化；取消、成功和页面离开后不继承旧状态；定向测试和 Debug 构建通过。
• 待确认项：需要安装新 APK，在现场复现 IO_TIMEOUT -> 确认 -> PROTOCOL_ERROR 链路并验证第二个弹框及再次恢复。

实现

• ReaderInitializationRetryGate 增加 retryInProgress，确认重试后才允许 PROTOCOL_ERROR 再次获取弹框资格。
• 普通状态下 PROTOCOL_ERROR 仍被排除，避免把读卡协议异常误报成连接异常。
• 新增文案“读卡器初始化失败，是否重新初始化？”，与连接异常提示明确区分。
• 用户取消、初始化成功、页面离开或重试未被接受时清理重试上下文。

测试与验证

• TDD RED：先增加“确认重试后协议错误再次提示”和“取消后不再追踪”测试，旧门禁因缺少重试上下文接口而编译失败。
• 定向测试：ReaderInitializationRetryGateTest 9 个测试、CardSearchStateMachineTest 4 个测试通过，合计 13 个，0 failure、0 error、0 skipped。
• 完整单元测试：共执行 204 个测试，其中 3 个既有 CustomerFullFetchServiceTest 失败；当前实现分页大小为 2000，而测试仍按 1000 断言。本次未修改该人员同步范围。
• Debug 构建：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:assembleDebug，构建成功。
• APK：app/build/outputs/apk/debug/app-debug.apk，大小 67020699 字节，SHA-256 a5801c6ab89c62eafcee1b5122beae5f5609da093027d74cb689e9a72ef18e47。
• 本次未安装 APK、未操作现场读卡器、未触发真实订单或扣款。

Git 边界

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