2026-08-26 读卡器 HID 32/64 字节自动兼容变更记录

变更结论

已将一卡通 USB HID 链路从固定 32 字节改为连接级动态 profile。同一套业务代码会根据读卡器 HID 接口的 Interrupt 端点拓扑选择 32/32 或 64/64 字节，并在未知拓扑下安全拒绝连接。

根因与识别依据

• 两款读卡器的 VID/PID 和产品名相同，不能据此区分报文长度。
• 读卡器 A 的 Report Descriptor 声明 32/32 字节，Android 枚举为 1 IN + 0 OUT。
• 读卡器 B 的 Report Descriptor 声明 64/64 字节，Android 枚举为 1 IN + 1 OUT。
• 终端 CPU/Android 的 32 位或 64 位与 HID 报文长度无关。
• F700 Android 11 无法通过 USB Host API 返回 Report Descriptor，因此实现采用已实测且 Android 可稳定读取的端点拓扑，不使用序列号或试发指令。

项目文件变更

• 新增 HidReportProfile，保存一次物理连接不可变的输入、输出报告长度。
• 新增 HidReportProfileSelector，集中维护两种已验证的端点拓扑映射；未知组合返回 UNSUPPORTED_HID_REPORT。
• AndroidUsbHidTransport 在连接时统计 Interrupt IN/OUT，选择 profile，动态分配接收缓冲区并严格校验收发长度；断开时清除 profile。
• HidFrameCodec 的组包、分包、继续请求和响应解析改为接受明确的 report 长度。
• HidTransport 暴露当前 profile；NewcapecProtocol 在一次交换开始时捕获并贯穿全部协议片段。
• 保留厂商协议规定的 24 字节逻辑分段和 CONTROL_SET_REPORT 写入路径。
• 删除在目标 Android 主机上不可用的 Report Descriptor 读取、解析试验代码，避免死代码和错误降级。

测试与构建

• HidReportProfileSelectorTest 按 TDD 先 RED 后 GREEN，覆盖 1/0 → 32、1/1 → 64 和未知拓扑拒绝。
• HidFrameCodecTest 覆盖 32/64 字节请求、响应和长度不匹配。
• NewcapecProtocolReportProfileTest 验证协议初始化的全部报告跟随连接 profile。
• 使用 JDK 8 执行 :app:testDebugUnitTest :app:assembleDebug，结果成功。
• Debug APK 已安装到当前 F700-HW。

64 字节读卡器真机证据

• 枚举：interruptInputCount=1 interruptOutputCount=1。
• 选择：inputReportBytes=64 outputReportBytes=64 source=USB_ENDPOINT_TOPOLOGY。
• 初始化：PROTOCOL_INITIALIZE_SUCCESS。
• 寻卡：连续 written=64、inputBytes=64，无长度错误或 USB 超时。
• 当前未放卡，返回 NO_CARD 属于预期业务结果。
• 退出页面后出现 DISCONNECT_SUCCESS，接口和连接正常释放。

32 字节读卡器真机证据

• 实物序列号：0001A0000001。
• 枚举：interruptInputCount=1 interruptOutputCount=0。
• 选择：inputReportBytes=32 outputReportBytes=32 source=USB_ENDPOINT_TOPOLOGY。
• 初始化：PROTOCOL_INITIALIZE_SUCCESS。
• 寻卡：连续多轮 written=32、inputBytes=32，无长度错误或 USB 超时。
• 当前未放卡，返回 NO_CARD 属于预期业务结果。
• 退出页面后出现 USB_CLOSE_SUCCESS 和 DISCONNECT_SUCCESS，接口和连接正常释放。

范围与安全边界

• 未修改一卡通 APDU、余额、扣款、人员同步和页面业务逻辑。
• 未执行真实消费；交易结果未知保护保持不变。
• 当前设备访问 10.128.1.19:80 的人员同步失败属于独立网络问题。
• 未执行 Git 暂存、提交、推送、分支切换或其他 Git 写操作。