读卡器 HID 32/64 字节报文自动兼容实施计划

计划状态

• 日期：2026-08-26
• 状态：代码、自动化验证和 32/64 字节两款真机验收均已完成
• 目标：同一套代码按 USB 中断端点拓扑自动选择 32/32 或 64/64 字节连接级 profile
• 技术栈：Java 8、Android USB Host API、JUnit 4、Gradle 5.1.1

实施边界

• 仅调整 onecard/reader 的 HID 连接、组包和协议配置传递。
• 不修改一卡通 APDU、寻卡语义、消费规则、人员同步或页面交互。
• 不按序列号或终端 32/64 位判断。
• 不通过发送业务指令试探报文长度。
• 不执行真实扣款。
• 不执行 Git 暂存、提交、推送、分支切换等写操作。

文件清单

新增

• HidReportProfile.java：保存一次连接的不可变 input/output report 长度。
• HidReportProfileSelector.java：集中维护端点拓扑到 profile 的安全映射。
• HidReportProfileSelectorTest.java：覆盖两种已验证拓扑和未知拓扑。
• NewcapecProtocolReportProfileTest.java：验证协议层始终跟随连接 profile。

修改

• ReaderError.java：增加 UNSUPPORTED_HID_REPORT。
• HidFrameCodec.java：组包、分包、继续请求和响应解析接受动态长度。
• HidTransport.java：暴露当前连接的不可变 profile。
• NewcapecProtocol.java：每次交换捕获一次 profile 并贯穿所有片段。
• AndroidUsbHidTransport.java：统计 Interrupt IN/OUT、选择 profile、动态收发并记录日志。
• HidFrameCodecTest.java：覆盖 32/64 字节和长度不匹配。

删除的试验代码

• HidReportDescriptorParser.java 及测试。
• UsbHidDescriptorParser.java 及测试。

删除原因：目标 F700 Android 11 在占用接口前后、使用宽缓冲区和精确声明长度三种方式下，均无法通过 USB Host API 读取 Report Descriptor。保留这些组件会形成不可达死代码。

任务 1：建立连接级 profile 与拓扑选择器

• 先编写失败测试，验证选择器尚不存在时测试为 RED。
• 实现 HidReportProfile，只接受 32 或 64 字节。
• 实现 HidReportProfileSelector：
  • 1 IN + 0 OUT → 32/32
  • 1 IN + 1 OUT → 64/64
  • 其他组合 → UNSUPPORTED_HID_REPORT
• 运行聚焦测试并确认 GREEN。

任务 2：让 HID 编解码支持动态长度

• 先把测试改为 32/64 参数化场景并确认旧接口失败。
• 将请求、分包、继续请求和响应解析改为显式传入 report 长度。
• 保留厂商协议规定的每段最大 24 字节逻辑负载。
• 按 Input Report 长度计算响应容量。
• 长度不匹配时返回明确错误。

任务 3：保证一次协议交换只使用一个 profile

• 为 HidTransport 增加 getReportProfile()。
• 为 32/64 两种 profile 编写协议初始化测试。
• 在 NewcapecProtocol.exchange() 开始时捕获一次 profile。
• 请求片段、响应解析和继续请求复用该 profile。

任务 4：接入 Android USB 传输层

• 枚举 HID 接口的 Interrupt IN/OUT 端点并统计数量。
• 在打开设备和协议初始化前完成 profile 选择。
• 未知拓扑记录诊断日志并安全拒绝连接。
• 输入缓冲区按 profile 动态分配。
• 输出数组、实际写入量和实际读取量按 profile 严格校验。
• 关闭连接时清除 profile。
• 日志记录 source=USB_ENDPOINT_TOPOLOGY。

任务 5：自动化验证

• HidReportProfileSelectorTest RED → GREEN。
• 全部 reader 单元测试通过。
• 完整 :app:testDebugUnitTest 通过。
• :app:assembleDebug 通过。
• 使用 JDK 8 构建。

执行命令：

JAVA_HOME=/Users/liang/Library/Java/JavaVirtualMachines/corretto-1.8.0_482/Contents/Home \
  bash gradlew :app:testDebugUnitTest :app:assembleDebug

任务 6：真机验收

64 字节读卡器 B

• 枚举结果为 interruptInputCount=1 interruptOutputCount=1。
• 自动选择 inputReportBytes=64 outputReportBytes=64。
• 协议初始化三段交互成功。
• 连续寻卡的 64 字节写入和读取成功。
• 未放卡时正确返回 NO_CARD，未出现长度错误或通信超时。
• 页面退出后连接正常释放。

32 字节读卡器 A

• 换入 A 后确认序列号为 0001A0000001，枚举结果为 1 IN + 0 OUT。
• 自动选择 inputReportBytes=32 outputReportBytes=32。
• 协议初始化成功，连续多轮寻卡均完成 32 字节写入和读取。
• 未放卡时正确返回 NO_CARD，未出现长度错误或 USB 超时。
• 页面退出后出现 DISCONNECT_SUCCESS，接口和连接正常释放。

消费边界

• 本次未执行真实消费。
• 现有 TRANSACTION_OUTCOME_UNKNOWN 保护未修改。
• 人员同步访问 10.128.1.19:80 失败属于独立网络环境问题，不纳入读卡器兼容改动。

完成标准

• 两款读卡器均无需人工选择型号。
• 每次插拔重新按端点拓扑选择 profile。
• 初始化、寻卡、读卡、消费和断开复用同一 profile。
• 未知拓扑在协议初始化前失败。
• 自动化测试、Debug 构建和两款真机基础链路全部通过。
• 形成匹配的 Markdown/HTML 设计、计划和变更记录。