绑盘机消费流程代码实施设计

版本：V1.2
日期：2026-08-28
需求基线：2026-08-27-consumption-product-requirements.md V0.9.6
视觉基线：方案 B“金额聚焦型”定稿

1. 记录目的

本文件把已确认的产品需求和方案 B 原型转换为代码边界、状态机、数据结构与验证策略，作为本次代码实施的直接依据。

记录原因：当前项目中已经存在一版消费诊断页、读卡扣款和接口 C 代码。如果直接覆盖，容易丢失已验证的硬件实现；先建立实施设计，可以区分“复用、修正、新增”三类改动，并为后续真机问题定位保留依据。

2. 当前代码基线

2.1 可复用能力

• 餐盘扫码器和移盘事件：PeripheralReader、ReaderFactory。
• 接口 B：POST /api/oneCardTerminal/acquireByPlate。
• 一卡通读卡与扣款：消费前读卡、补贴优先扣款、消费后复读。
• 接口 C 新版 JSON 请求：零元携卡结果与正金额成功结果均有契约测试。
• 读卡器 USB 自动发现、权限、连接和寻卡循环。
• 当前基线有 80 个单元测试，0 failure、0 error、0 skipped。

2.2 必须修正的差距

1. 当前页面是单页调试面板，不是方案 B 的三阶段用户页面。
2. 当前正金额订单需要用户点击“支付”，需求要求订单判断完成后自动进入支付页。
3. 当前订单协调器在移盘时使未返回的订单响应失效，需求要求查询继续并锁定本次餐盘会话。
4. 当前移盘会取消尚未开始的支付，需求要求移盘不打断已经进入的业务流程。
5. 当前语音及页面使用“请刷卡”，需求统一为“请放卡片进行支付”。
6. 当前仅日志记录交易结果，没有以订单号关联的结构化本地交易记录。
7. 当前接口 C 失败只展示在页面，没有持久化补传队列。
8. 当前消费页使用临时硬编码服务地址和模拟一分钱订单，正式实现必须使用设备配置地址并删除模拟订单路径。

3. 实施边界

3.1 本次实现

• 一个 ConsumptionActivity 承载三个互斥页面容器；业务上仍是三个页面阶段，避免三 Activity 之间丢失硬件会话。
• 独立纯 Java 状态机管理页面与业务阶段。
• 餐盘识别后锁定会话；移盘只更新“餐盘是否仍在”，不取消订单查询、读卡或反馈。
• 正金额订单自动武装读卡器并进入第三阶段。
• 交易前读卡、扣款、交易后读卡结果按订单号持久化。
• 接口 C 请求先落库再上传；上传成功标记完成，失败保留原请求并推进前台流程。
• 待上传记录每3分钟触发同步；每批50条、单轮最多2批；应用启动和网络恢复可触发即时同步；同一时刻只运行一个同步轮次。
• 明确区分交易失败和上传失败，禁止对扣款结果不确定的订单自动再次扣款。
• 零元订单进入第三阶段等待新卡，仅执行一次完整读卡；不调用消费接口，读卡成功后携卡信息反馈接口 C。

3.2 本次不实现

• 不修改服务端幂等逻辑。
• 不在本地自动模拟真实订单、真实扣款或接口 C 成功。
• 不通过自动化测试操作真实一卡通设备或真实资金卡。
• 不执行 Git 暂存、提交、推送、拉取、分支切换或历史改写。

4. 状态机设计

零元路径为 LOADING_ORDER → WAITING_CARD → READING_ZERO_AMOUNT_CARD → REPORTING；读取失败回到 WAITING_CARD，读取成功后不经过 DEBITING/READING_AFTER。正金额路径保持原三阶段。

ConsumptionUiStateMapper 是纯 Java 展示映射边界。ConsumptionFlowStateMachine 仍是唯一业务状态源；页面合并不影响阶段日志、持久化或接口 C。

终态复位规则：餐盘仍在时保持当前结果；餐盘已移走且读卡区无卡时，满足最短展示时间后回到 WAITING_TRAY。

5. 餐盘会话规则

• 第一次有效餐盘码创建会话并锁定餐盘读取。
• 锁定期间忽略重复码和其他餐盘码，防止订单上下文被覆盖。
• TRAY_REMOVED 只把 tray_present 改为 false，不使接口 B 响应失效、不取消已武装交易、不打断硬件指令。
• 当前订单进入终态并完成页面展示后才解锁读盘。
• 页面停止或销毁属于生命周期退出，可以关闭本地会话；不能把已落库的接口 C 待上传记录删除。

6. 交易失败与反馈规则

6.1 不调用接口 C

• 零元单尚未取得完整卡信息或本次读卡失败。
• 消费前读卡失败。
• 余额不足、卡状态无效、账户不匹配等在扣款指令前已明确终止的失败。
• 卡片在扣款前被拿走。
• 扣款命令结果不确定、部分扣款、消费后复读失败或卡片更换。

这些场景必须保存本地交易阶段结果，其中结果不确定和部分扣款必须标记“禁止自动重扣”。

6.2 调用接口 C

• 请求顶层必须携带 equipment_code。设备编号在餐盘会话开始时从 SETTING_TERMINAL_CODE 读取、去除首尾空白并锁定；接口 B 获取订单、零元反馈和正金额反馈共用同一快照。
• 零元单：code=0、amount=0，只物理读卡一次，前后卡信息镜像同一真实读卡快照，不携带 PSAM/TAC。
• 正金额完整成功：携带消费前读卡、完整扣款结果和消费后读卡。
• 只有底层能够提供真实非零失败码，并且能够确认实际扣款金额为0时，才构造明确扣款失败反馈；不得使用枚举序号或本地臆造数字作为服务端失败码。

6.3 上传失败

• 网络失败、超时、空响应或服务端业务码非0都属于上传失败。
• 上传失败不改变原交易结果，不重新扣款，不阻塞前台进入终态。
• 保存完整的原始接口 C JSON；补传必须复用同一订单号和同一请求快照。
• 后台补传不得重新读取当前设备配置；即使设备设置已变化，也必须继续发送交易发生时入队请求中的 equipment_code。

7. 本地数据设计

本地数据库以 order_no 为业务关联键，至少保存：

• 餐盘码、订单金额、创建及更新时间。
• 消费前读卡结果 JSON。
• 扣款结果 JSON。
• 消费后读卡结果 JSON。
• 零元读卡交易保存前读卡快照、attempted=false 的扣款快照和空的物理后读卡快照；接口字段镜像只发生在请求构造层。
• 交易状态、失败阶段、错误码及错误信息。
• 接口 C 原始请求 JSON。
• 上传状态、上传次数、最近失败原因、下次允许重试时间。

记录原因：页面状态和日志不能承担应用重启后的恢复；结构化记录用于可靠补传、问题核对和避免重复扣款。

8. 增量实施顺序

1. 状态机及餐盘会话规则，先用纯 Java 单测锁定。
2. 本地交易仓库、接口 C 请求快照和补传策略。
3. 读卡阶段进度回调、零元只读分支及交易结果分类。
4. 方案 B 三页面布局和 Activity 编排。
5. 应用启动、3分钟定时及网络恢复触发。
6. 全量单测、Debug 构建、资源检查和真机待验清单。

9. 验证策略

• 每个切片先运行定向单测，再运行全量 :app:testDebugUnitTest。
• 最终运行 :app:testDebugUnitTest :app:assembleDebug。
• 检查零元请求前后卡镜像、金额单位、PSAM/TAC 缺失和原请求补传一致性。
• 检查页面文案中不再出现“请刷卡”。
• 检查源码不再包含临时测试地址和模拟一分钱订单。
• 真机阶段重点验证零元单单次读卡无写卡、零元读卡失败重试、餐盘提前移走、正金额卡片在三个阶段移走、断网补传和应用重启恢复。

10. 零元只读实现边界

• ConsumptionTransactionGate 接受非负金额；负金额仍拒绝。金额为 0 只代表只读事务，不能触发消费。
• ConsumptionCardTransactionExecutor 先执行一次 readCard(expectedUid)；金额为 0 时立即返回，consumptionAttempted=false，不调用 consumeSubsidyFirst，不执行第二次物理读卡。
• ConsumptionFlowStateMachine 使用独立的 READING_ZERO_AMOUNT_CARD 状态，读卡失败可安全回到 WAITING_CARD。
• OneCardDebitReportRequest.forZeroAmountOrder(orderNo, equipmentCode, cardInfo) 强制要求非空设备编号和卡信息，并在协议边界将同一快照映射到 before_card_info、after_card_info。
• ConsumptionActivity 仅在零元读卡成功后入队反馈；读卡失败保存 ZERO_AMOUNT_CARD_READ_FAILED 并等待移卡后重试。

11. 卡片人员与余额展示

• ConsumptionCardTransactionExecutor.ProgressListener 在首次完整读卡成功后通过默认方法上送 CardInfo，回调发生在消费指令之前；默认空实现保持已有阶段 Lambda 兼容。
• ConsumptionCardSearchManager 只对当前有效会话转发卡片快照，避免迟到回调污染下一笔订单。
• ConsumptionActivity 使用 customerId 从 SQLiteCustomerRepository 查询 NAME；未同步或本地查询异常只降级页面姓名，不阻断交易。
• 首次快照展示持卡人、补贴余额和现金余额；正金额交易只有完整后读卡和业务校验通过后才标记为结算后余额。
• 后读卡存在但交易结果不确定时可以展示最新真实读卡值，但仍标记为读卡时余额；禁止使用计算余额冒充真实复读结果。
• 新餐盘会话和统一复位均清空卡片展示快照；姓名不新增到普通业务日志。

12. 页面资源边界

• 放盘、放卡、取卡分别使用新生成的透明 PNG，同一色板、画布和视角，不再使用绑盘成功/失败或旧刷卡图。
• 订单成功后直接调用交易武装，不保留固定一秒的订单成功过渡状态。
• 正常读卡器连接状态不占用主视觉区；只有阻断操作的错误显示在页面。
• 页面尺寸、颜色和所有用户文案继续使用 Android 资源，不在 Java 或布局中散落魔法值。