一卡通设置读卡器调试变更记录

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

结论：在“设置 → 一卡通设置”新增“读卡器调试”，可依次手动执行连接读卡器、寻卡和读卡，并展示卡片信息及原始响应；调试过程不会触发消费或扣款。

Compact Use Case

• Use Case ID / 状态 / DoR：UC-READER-DEBUG-001 / Done / READY
• 角色、触发与目标：现场实施或维护人员在设置页检查新开普 USB 一卡通读卡器，快速区分设备连接、寻卡和完整读卡阶段的问题。
• In Scope / Out of Scope：新增设置入口、手动调试弹框、USB 权限申请、单线程命令门禁、读卡结果展示和生命周期释放；不修改一卡通协议、消费订单、扣款逻辑、WebService 配置和上传流程。
• 主流程：进入读卡器调试 → 连接读卡器并完成协议初始化 → 放卡后执行寻卡 → 使用本次寻得的 UID 完整读卡 → 展示 UID、卡号、人员编号、卡类别、卡类型、卡状态、余额、应用序列号和原始响应。
• 边界或异常/恢复：未连接时不允许寻卡，未寻卡时不允许读卡；命令执行期间禁用全部操作；读卡失败后必须重新寻卡；设备拔出后回到重新连接状态；关闭弹框或销毁设置页时注销 USB 广播并串行断开读卡器。
• 安全边界：调试控制器只调用 connect、findCard、readCard 和 disconnect，不装配订单、不调用 consume，因此不会发送扣款指令。
• 验收标准：入口位置正确；三项操作顺序和按钮状态正确；USB 权限、无设备、拔出和协议错误均可展示结果；退出后释放资源；单测和 Debug 构建完成验证。
• 待确认项：需要在现场使用目标 USB 读卡器和真实测试卡验证权限弹框、设备插拔、寻卡、字段展示及原始响应滚动查看。

实现

• SetOnecardFragment 增加“读卡器调试”设置项并管理调试弹框生命周期。
• 新增 OnecardReaderDebugDialog，提供“连接读卡器、寻卡、读卡”三个明确操作及可滚动、可选择的结果区域。
• 新增 OnecardReaderDebugController，复用 NewcapecUsbCardReader，负责 USB 设备发现、权限结果、单线程 I/O、独立读卡日志会话、拔出监听和关闭释放。
• 新增 ReaderDebugCommandGate 与 ReaderDebugOperation，集中约束命令顺序和重复点击，避免 UI 自行维护分散状态。
• 新增的显示文案和尺寸均放入资源文件；类职责、USB 串行边界及 UID 失效原因均补充注释，没有在布局中散落新的固定尺寸。

测试与验证

• 定向测试：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:testDebugUnitTest --tests com.zhct.traybinding.onecard.reader.ReaderDebugCommandGateTest，4 个测试，0 failure、0 error、0 skipped。
• 完整单元测试：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:testDebugUnitTest --rerun-tasks，210 个测试中 207 个通过、3 个失败。

失败均为既有 CustomerFullFetchServiceTest 分页断言仍按 1000，而当前实现按 2000；本次未修改该范围。

• Debug 构建：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:assembleDebug，构建成功。
• APK：app/build/outputs/apk/debug/app-debug.apk，大小 67048780 字节，SHA-256 5e0bc41c8a2edfe8ad4a4a5710656296adc59246845a874f45703f0c7f51482d。
• 本次未安装 APK、未操作现场读卡器、未触发真实订单或扣款。

Git 边界

本次未执行暂存、提交、推送、拉取、分支切换或其他 Git 写操作；工作区内原有的一卡通服务器相关修改保持不变。