接口 C：反馈一卡通扣款结果——契约测试矩阵

范围与分类

接口：POST /api/oneCardTerminal/report
终端：设备端
模块：自研硬件 / 绑盘机 / 新开普一卡通
角色：消费终端设备
风险：金额、订单、一卡通扣款、设备集成、重复提交
契约基线：/Users/liang/Downloads/智慧营养健康餐厅.html

前置条件与测试数据

本地自动化只验证请求构造、序列化、参数保护和 Retrofit 注解，不发送真实扣款或服务端写请求。
正金额样例：订单 ORDER-002，设备 TERMINAL-001，金额 1234 分，包含消费前卡信息、两钱包扣款批次和消费后卡信息。
零元样例：订单 ORDER-001，设备 TERMINAL-001，金额 0 分，包含一次真实读卡快照，不包含 PSAM/TAC 数据。
真机联调需使用隔离测试环境、测试订单和测试卡；不得对生产订单或真实资金卡执行测试。

接口测试矩阵

编号	场景	期望	当前覆盖
C-01	正金额完整成功	JSON 含订单号、设备编号、成功扣款结果和完整前后卡信息；成功后服务端完成订单	请求映射已自动化；服务端副作用待测试环境联调
C-01A	设备编号会话一致性	接口 B 与接口 C 使用同一会话锁定的 `equipment_code`；入队补传保留原值	请求序列化和落库编解码已自动化；Activity 透传待真机观察
C-02	零元订单	先物理读卡一次；携带设备编号，`code=0`、`amount=0`，前后卡对象镜像同一真实快照，不触发扣款	已自动化
C-02A	零元单缺少卡信息	客户端拒绝构造成功反馈，不入队、不上传	已自动化
C-02B	零元单读卡失败	不调用接口 C；移卡后允许同一订单继续等待新卡	状态机、交易器已自动化；真机移卡待验
C-03	缺少订单号	客户端拒绝构造请求	已自动化
C-03A	缺少设备编号	客户端拒绝构造请求，不入队、不上传	已自动化
C-04	缺少前读卡、扣款未完成或缺少后读卡	不得按成功结果调用接口	已自动化请求保护；页面分支由现有交易流程覆盖
C-05	服务端返回业务失败	页面提示反馈失败；正金额不得再次扣款	页面逻辑已实现；待联调回读
C-06	网络超时或无响应	保留扣款已完成状态并禁止再次扣款	页面逻辑已实现；应用重启可靠重传未实现
C-07	重复提交同一成功订单	服务端应按文档幂等返回成功	待测试环境联调
C-08	成功订单后提交失败结果	服务端应拒绝覆盖成功状态	当前客户端无此调用；服务端待验证
C-09	未同步人员	服务端返回业务失败，订单保持待支付	待测试环境联调
C-10	多钱包分段扣款	`amount` 为实际扣款总额；单组 PSAM/TAC 取最后一段成功交易	业务规则已确认，请求映射已自动化
C-11	鉴权失败	按部署链路返回失败，不完成订单	用户要求客户端忽略 Access-Token；待环境验证
C-12	并发与压力	不重复扣款、反馈延迟满足设备结算体验	涉及真实设备和订单副作用，当前标记不可本地自动化

套件归属

Smoke：C-01、C-01A、C-02、C-05。
设备主流程：C-01、C-04、C-06、C-10。
模块回归：C-01A、C-02、C-02A、C-02B、C-03、C-03A、C-04。
异常与边界：C-03、C-03A、C-05、C-06、C-08、C-09、C-11。
幂等与重复提交：C-07、C-08。
性能与压力：C-12；必须在隔离测试环境执行，不能使用生产订单或真实资金卡。

本地执行记录（2026-08-28）

RED：新版测试首次运行因 forSuccessfulDebit(...) 尚不存在而编译失败。
GREEN：接口请求映射、Retrofit JSON @Body 契约及金额策略定向测试通过。
全量命令：JAVA_HOME=.../corretto-1.8.0_482/Contents/Home bash gradlew :app:testDebugUnitTest :app:assembleDebug --rerun-tasks。
完整构建结果：BUILD SUCCESSFUL in 23s，Debug APK 构建成功。
补充边界用例 C-03、C-04 后重新执行全量单测：80 个测试、0 failure、0 error、0 skipped，BUILD SUCCESSFUL in 3s。
零元读卡变更先增加状态机、交易闸门、交易执行器、反馈映射和落库编解码定向测试；旧实现因缺少 READING_ZERO_AMOUNT_CARD 及带卡信息的零元反馈工厂而按预期编译失败。
实现只读卡分支后，上述 5 组定向测试通过；最终完整单测及 Debug 构建为 BUILD SUCCESSFUL in 21s，105 个测试、0 failure、0 error、0 skipped。
2026-08-29 增加 equipment_code 契约：旧实现因工厂方法缺少设备编号参数产生 7 处预期编译失败；实现会话锁定、请求校验和序列化后，两组定向测试 BUILD SUCCESSFUL in 6s。

通过标准与剩余风险

本地契约层通过标准为：新版字段名与嵌套结构准确、零元与正金额请求携带设备编号、空设备编号被拒绝、落库补传保留原设备编号、零元前后卡镜像真实快照、零元缺卡请求被拒绝、完整正金额数据可序列化、不完整成功请求被拒绝、Debug 构建成功。C-10 的多钱包字段规则已经确认；接口端到端验收仍需完成 C-01、C-01A、C-05、C-06、C-07、C-09、C-11，并在真机确认零元路径没有消费 APDU。