首次读卡后卡状态校验变更记录

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

结论：所有订单在第一次完整读卡后统一校验卡状态；只有状态 241 / 0xF1 可以继续，挂失、冻结及未知状态卡均在扣款前拦截并提示换卡。

Compact Use Case

• Use Case ID / 状态 / DoR：UC-CARD-STATUS-001 / Done / READY
• 角色、触发与目标：就餐人员对零元或非零订单放卡后，终端立即判断卡片是否具备消费资格，防止异常卡完成核验或进入扣款。
• In Scope / Out of Scope：新增首次读卡后的统一状态判断、异常提示、换卡重试、本地记录和回归测试；不改变读卡协议字段、扣款算法、订单接口和一卡通上传协议。
• 主流程：第一次完整读卡并保存快照后判断状态；241 继续原有零元核验或扣款流程，其他状态停止后续硬件交易。
• 边界或异常/恢复：异常卡只读取一次，不扣款、不执行第二次读卡、不发送结算成功反馈、不生成一卡通扣款上传；移卡后保留当前订单，可换正常卡重试。
• 业务规则：241 / 0xF1 正常；243 / 0xF3 挂失；244 / 0xF4 冻结；其他值未知。除正常状态外全部不可消费。
• 用户提示：主提示统一为“卡状态异常，不可消费”；挂失提示“此卡已挂失，请更换其他卡片”；冻结提示“此卡已冻结，请更换其他卡片”；未知状态提示“无法识别当前卡状态，请联系工作人员”；操作提示为“请拿走卡片”。
• 验收标准：状态映射准确；零元和非零订单均在首次读卡后拦截；异常卡不触发扣款或二次读卡；移卡后当前订单可换卡；完整单测和 Debug 构建通过。
• 性能/安全：仅增加本地常量判断，不增加网络请求；协议层保留同一状态策略作为第二道扣款保护。
• 待确认项：需要现场使用 241、243、244 及一个其他状态的测试卡完成真机视觉与硬件验收。

实现

• 新增 CardConsumptionStatusPolicy，集中管理正常、挂失、冻结和未知状态，避免多个入口硬编码不同规则。
• ConsumptionCardTransactionExecutor 在首次读卡快照回调后、零元分支和扣款阶段之前执行状态校验。
• NewcapecProtocol 继续在协议扣款入口校验卡状态，并复用统一策略，防止其他调用入口绕过。
• 消费状态机新增异常卡返回等待放卡的转换；交易门禁在未尝试扣款时保持武装，移卡后允许当前订单换卡重试。
• 消费页复用整页错误样式和移卡图标，根据挂失、冻结、未知状态展示对应说明，不使用短暂 Toast。
• 异常卡本地保存为 CARD_STATUS_REJECTED，并记录 CARD_STATUS_INVALID、十进制状态、十六进制状态和分类。

测试与验证

• TDD RED：JDK 8 下新增测试在实现前因缺少 CardConsumptionStatusPolicy 和 onCardRejected() 编译失败。
• 定向测试：状态策略 4 个、交易执行器 11 个、消费状态机 10 个测试通过。
• 完整单元测试：JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:testDebugUnitTest --rerun-tasks，195 个测试，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，大小 67134272 字节，SHA-256 7774a6730b0a3d81408bb68e672b3ff358e4350720481935cdf2bfa366ed3ec4。
• 本次未安装 APK、未操作现场设备、未触发真实订单或扣款。

Git 边界

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