2026-08-28 零元单读卡核验与携卡反馈变更记录

需求

获取到金额为 0 的订单后，不再立即发送空卡信息反馈。终端必须等待用户放卡，完成一次真实读卡，并在不执行任何扣款或写卡指令的前提下，携带卡片信息反馈接口 C。

实现

• 零元单和正金额订单统一进入第三步等待新卡；第三步标题调整为“卡片结算”。
• 状态机新增 READING_ZERO_AMOUNT_CARD，零元读卡失败可以安全返回 WAITING_CARD。
• 交易闸门接受金额 0 的只读事务，仍拒绝负金额。
• 卡交易执行器在零元订单中只调用一次 readCard(expectedUid)，随后立即返回；不调用 consumeSubsidyFirst，不执行第二次物理读卡。
• 接口 C 零元请求强制要求非空 CardInfo；before_card_info 与 after_card_info 镜像同一真实快照，amount=0，且不携带 psamID/psamJyNo/tac。
• 零元读卡失败保存 ZERO_AMOUNT_CARD_READ_FAILED，不生成成功反馈；用户移卡后继续等待下一次放卡。
• 零元读卡成功保存 ZERO_AMOUNT_CARD_READ_SUCCEEDED，接口请求先落库再上传；上传失败继续使用原请求后台补传。
• 零元单完成或待补传时，同样等待用户取卡后才能复位，避免卡片滞留影响下一单。

页面文案

• 等待放卡：本单金额为 0 元，请放卡核验。
• 辅助说明：读取卡片信息后将自动完成结算，不会扣款。
• 读卡中：正在读取卡片信息 / 零元核验中，请勿移动卡片。
• 读卡成功：卡片读取成功，可拿走卡片。
• 零元流程不播放现有“请放卡片进行支付”语音，避免传达错误扣款语义。

自动化测试

• 状态机：零元订单进入等待卡片和独立只读状态；读卡失败可以回到等待卡片。
• 交易闸门：金额 0 可以武装，负金额仍被拒绝。
• 交易执行器：零元路径只产生一次 read，没有 consume 和第二次 read。
• 接口契约：前后卡对象完整且相同；金额为 0；不包含 PSAM/TAC；缺卡信息时拒绝构造请求。
• 补传快照：携卡零元请求序列化、落库、恢复后内容保持一致。

本地验证结果

• 命令：JAVA_HOME=/Users/liang/Library/Java/JavaVirtualMachines/corretto-1.8.0_482/Contents/Home bash ./gradlew :app:testDebugUnitTest :app:assembleDebug --no-daemon --console=plain。
• 结果：最终复跑 BUILD SUCCESSFUL in 21s。
• 单测报告：31 个测试类，105 个测试，0 failure、0 error、0 skipped。
• Debug APK：app/build/outputs/apk/debug/app-debug.apk，64,336,640 字节。
• git diff --check 通过；当前代码和基线文档中不再残留 ZERO_REPORTING、零元空卡对象工厂或“零元订单不寻卡”表述。
• 旧 Android 构建环境仍输出 SDK schema 映射和 Java 8 build-tools 警告，不影响构建结果。

文档同步

• 产品需求更新到 V0.9.5。
• 代码实施设计更新到 V1.1。
• 接口 C 契约矩阵增加 C-02A、C-02B。
• 实施工作日志增加 R-17。
• 上述正式文档均同步维护同名 Markdown 与 HTML。
• 为订单确认展示时长、终态结果展示时长和日志值最大长度常量补充职责、单位及边界说明；未调整常量值或业务逻辑。

风险与真机验收

• 本地自动化能够证明代码路径不调用消费方法，但无法替代真实读卡器线缆级验证。
• 真机需检查零元单没有消费 APDU，卡余额和消费次数不变化。
• 服务端需确认零元请求的前后卡对象均收到同一卡片完整字段，并按订单号完成结算。
• 读卡失败、遗留卡、移卡后重试、接口 C 断网补传需要在目标设备验证。

Git 边界

本次只修改代码、测试和文档，不执行暂存、提交、推送、拉取、分支切换或历史改写。