2026-08-27 消费页一卡通扣款结果反馈变更记录

目标与来源

按新版 Apifox“接口 C：反馈一卡通扣款结果”替换旧契约。零元订单不读卡、不扣款，扣款成功码和金额均传 0，无卡片数据使用空 JSON；正金额订单在消费成功且再次读卡成功后，将消费前读卡、扣款结果和消费后读卡一并反馈。

接口来源：用户提供的 Apifox 项目导出文件 /Users/liang/Downloads/智慧营养健康餐厅.html，Apifox 项目。

接口契约

POST /api/oneCardTerminal/report，使用 application/json。
顶层字段：order_no、settlement_result、before_card_info、after_card_info。
扣款结果包含 code、message、amount、psamID、psamJyNo、tac。
消费前后卡信息包含新版契约规定的 13 个卡片字段。
零元订单使用 {"code":0,"amount":0}，两个卡信息对象均为 {}，不输出无来源的 PSAM/TAC。
正金额取实际完成扣款总额和真实前后读卡信息；用户已确认多钱包分段扣款时，接口单组凭证取最后一段成功交易。
响应复用 NetworkResult<List<Object>>；本次未新增或硬编码 Token。

实际改动

反馈请求模型由旧表单六字段改为新版嵌套 JSON，分别支持零元和正金额成功订单。
Retrofit 由 @FormUrlEncoded + @Field 改为 @Body 请求对象。
新增金额策略：正金额进入卡支付，零元进入免扣款反馈，负金额无效。
零元订单不武装读卡器；正金额只有前读卡、完整扣款和后读卡均成功后才反馈。
反馈成功后显示结算完成；反馈失败提示扣款已发生且禁止再次扣款，并写入本地日志。
迟到响应会核对当前订单，避免旧订单结果污染新流程。

TDD 与验证证据

RED

先更新新版 JSON 契约测试。JDK 8 下首次运行按预期因生产代码尚无 forSuccessfulDebit(...) 而编译失败，证明测试先于实现生效。

GREEN

JSON 请求体、零元成功码/0 分/空卡对象、正金额三阶段映射和金额分支的定向测试通过。

JAVA_HOME=/Users/liang/Library/Java/JavaVirtualMachines/corretto-1.8.0_482/Contents/Home \
bash gradlew :app:testDebugUnitTest \
  --tests 'com.zhct.traybinding.network.request.OneCardDebitReportRequestTest' \
  --tests 'com.zhct.traybinding.consumption.ConsumptionOrderPaymentPolicyTest' \
  --tests 'com.zhct.traybinding.network.CPTNetworkRequestReportContractTest'

全量验证

:app:testDebugUnitTest :app:assembleDebug --rerun-tasks 返回 BUILD SUCCESSFUL in 23s；补充边界测试后再次执行全量单测为 80 个测试、0 failure、0 error、0 skipped；Debug APK 于 2026-08-27 17:57 生成，约 61 MB。

风险与待联调项

需联调确认服务端接受零元成功结果和两个空卡对象。
多钱包规则已确认：amount 传实际扣款总额，单组 PSAM/TAC 取最后一段成功交易。
需真机确认零元不启动扣款、正金额成功后只反馈一次。
尚无离线队列或持久化补偿；应用重启后的可靠重传属于后续需求。
本次未改产品原型，状态文案仅服务于当前诊断页。

Git 与范围边界

未执行 Git 暂存、提交、推送、拉取、合并、分支切换、重置或清理。工作区原有未提交改动保持原样。本记录不代表完整三步消费需求已经评审或实现。