绑盘机消费功能产品需求文档

1. 文档信息

2. 背景与业务目标

当前消费页已经具备餐盘识别、订单查询、一卡通读卡与扣款的基础能力，但现有页面偏调试展示，流程、异常提示和结算反馈仍不够产品化。本需求将消费过程整理为与绑盘页面一致的三步引导流程，并围绕“一笔订单只能安全结算一次”建立完整业务闭环。

业务目标：

1. 用户只需完成放盘和放卡两个必要动作；餐盘何时拿走由用户自行决定，不影响当前业务流程。
2. 根据订单金额自动判断零元结算或一卡通支付，不要求用户点击“支付”按钮。
3. 餐盘提前拿走时订单查询继续，且不能误识别下一只餐盘。
4. 卡片在交易过程中被拿走时立即中断后续操作，并根据已执行阶段给出准确提示。
5. 扣款一旦可能发生，系统绝不自动再次扣款。
6. 订单信息、消费前读卡、扣款结果、消费后读卡和服务端反馈结果必须关联保存，支持追溯与补偿。

3. 范围

3.1 本期范围

• 三个主页面及页面间自动切换。
• 餐盘识别、订单获取和金额判断。
• 零元订单等待新卡、只读卡核验和携卡信息反馈。
• 正金额订单的一卡通前读卡、扣款、后读卡和结果反馈。
• 餐盘提前移除、卡片中途移除、网络失败、硬件失败和应用重启后的安全处理原则。
• 新卡入场校验、页面生命周期、USB 断连和安全复位规则。
• 本地交易记录、反馈补偿、幂等与防重复扣款要求。
• 页面文案、语音和验收标准。

3.2 非本期范围

• 其他支付方式，如微信、支付宝、现金或人脸支付。
• 退款、撤销、冲正和人工补扣页面。
• 服务端订单金额计算规则。
• 一卡通 APDU、PSAM 和钱包扣款协议本身的改造。
• 后台对账与异常交易管理页面；本期只定义终端必须提供的数据基础。

4. 术语

5. 已确认业务规则

1. 消费流程采用三个页面，视觉与交互节奏参考现有绑盘三步页面。
2. 第一步识别餐盘成功后自动进入第二步。
3. 第二步只显示订单确认中的必要提示；订单成功后直接进入第三步，订单金额在第三步集中展示，是否支付仍只根据订单金额判断。
4. amount = 0 为零元单，不进行一卡通消费，但必须进入第三步等待新卡、读取一次完整卡片信息后调用接口 C。
5. amount > 0 进入一卡通支付流程；amount < 0 或金额缺失视为无效订单。
6. 获取订单和支付过程中对餐盘保持中性，不提示拿走，也不提示不要拿走；餐盘被拿走后请求与判断仍继续。
7. 识别餐盘后锁定当前餐盘会话，直到订单进入安全终态并完成统一复位；锁盘期间不能让下一只餐盘覆盖当前订单。
8. 所有有效订单自动进入第三步；零元单执行读卡核验，正金额执行读卡扣款，餐盘是否已经拿走不影响页面切换。
9. 正金额第三步使用语音“请放卡片进行支付”；零元单使用“本单金额为 0 元，请放卡核验”页面文案且不播放带“支付”含义的语音。
10. 卡片交易期间不得拿走卡片；拿走后按实际执行阶段提示并中断后续交易。
11. 发生卡片中途移除后：餐盘未拿走则停留在异常状态，直至餐盘拿走；餐盘已拿走则结束本轮并返回第一步。
12. 零元单读卡成功后携带真实卡片信息调用接口 C；正金额扣款成功后携带前读卡、扣款结果和后读卡结果调用接口 C。
13. 多钱包分段扣款时，amount 传实际扣款总额，psamID/psamJyNo/tac 取最后一段成功交易。
14. 客户端本次不单独处理 Access-Token。
15. 第三步必须等待一次“读卡区无卡 → 新卡放入”的完整事件，不能直接使用进入页面前已停留在读卡区的卡片。
16. 卡片保护窗口在后读卡完整成功后结束；之后接口 C 的网络反馈继续执行，但不再要求用户保留卡片。
17. 接口 C 仅在系统配置 meal_model = 4 时启用，本功能也只在该模式下开放。
18. 接口 C 上传成功或失败都必须推进前台业务；上传失败时先保存完整请求快照并进入后台补传，不得占用设备阻塞下一笔订单。
19. 待上传记录每 3 分钟同步一次，每批最多 50 条；积压时同轮最多连续处理 2 批，即最多 100 条。
20. 扣款前失败只保存本地记录并结束当前会话，不调用接口 C。
21. 扣款指令明确成功时按成功格式调用接口 C；扣款指令返回明确失败且实际扣款金额为 0 时，按失败格式调用接口 C。
22. 部分扣款、扣款结果不确定、后读卡失败或前后卡身份校验失败不得伪装为通用扣款失败，只保存本地异常并禁止自动再次扣款。
23. 接口 C 上传失败与一卡通交易失败是两类独立状态；上传失败只触发原请求补传，前台业务继续统一复位。
24. 页面展示状态与业务状态分离；前读卡、扣款、后读卡和结果反馈不得形成频繁切换的独立用户页面。
25. 首次完整读卡后，第三步必须显示持卡人、补贴余额和现金余额；姓名通过 customerId 查询本地人员库，未同步时不得阻断交易。
26. 正金额完整成功后使用真实后读卡快照更新结算后余额；零元单显示读卡余额；异常场景不得用计算值或扣款前余额冒充结算后余额。
27. 新订单开始和统一复位时必须清空上一位用户的姓名、余额与卡片快照。

6. 关键产品决策与旧逻辑替换

6.1 采用方案

采用“单订单会话状态机 + 三页展示”的方案。三个页面只是同一订单状态的不同展示阶段，订单号是贯穿订单、卡片交易、本地记录和接口反馈的唯一业务关联键。

相较于“每页独立处理”或“一个页面堆叠全部状态”，该方案更适合处理餐盘提前移除、网络迟到、卡片移除和扣款后反馈失败，能避免页面切换造成交易状态丢失。

6.2 新规则覆盖旧规则

• 旧逻辑中的“订单成功后点击支付按钮”被本需求的自动流程替换，不再要求用户二次点击。
• 旧提示“请刷卡”替换为“请放卡片进行支付”。
• 旧“零元单直接反馈、前后卡信息为空”的规则被替换：零元单必须等待新卡并完成一次只读卡核验，反馈前后卡字段镜像同一真实读卡快照。
• 关于餐盘动作的最终确认规则为“中性兼容”：订单查询和支付过程中不提示、不鼓励用户拿走餐盘，也不要求餐盘保持不动；拿走或保留餐盘都不打断当前业务流程。只有订单进入完成或异常终态、需要结束本轮会话时，才可提示用户拿走仍在设备上的餐盘。卡片进入交易后仍严格禁止拿走卡片。
• 餐盘移走只改变页面提示和流程收尾条件，不中断已经发出的订单请求，也不强行中断已经开始的卡片硬件指令。

6.3 当前实现与本 PRD 的主要差距

以下差距已经通过当前源码核对，后续不能只做页面换肤：

1. 当前 ConsumptionOrderCoordinator.onTrayRemoved() 会让未返回的订单请求失效；本需求要求查询继续并锁定本轮会话。
2. 当前流程需要用户点击支付按钮，再武装读卡交易；本需求要求正金额判断完成后自动进入第三步。
3. 当前页面和本地语音仍使用“请刷卡”；本需求统一改为“请放卡片进行支付”。
4. 当前消费页是订单、硬件结果和原始数据并列的调试面板；本需求需要三个面向用餐者的独立步骤页。
5. 当前接口 C 已支持零元和完整成功结果，但尚未形成应用重启后可恢复的持久化补传队列。
6. 当前卡交易结果主要保存在页面状态和日志中，尚缺以订单号为主键的结构化本地交易记录及异常核对状态。
7. 当前零元单直接反馈且卡信息为空；本次变更要求读卡成功后才能反馈，读卡失败则移卡后继续等待，不得生成成功反馈。

7. 总体业务流程

flowchart TD
    A[第一步：等待放盘] -->|识别成功并锁盘| B[第二步：获取订单]
    B -->|订单请求中| C{餐盘是否拿走}
    C -->|否| D[继续查询，不提示餐盘动作]
    C -->|是| E[记录已移盘但流程继续]
    D --> F{订单金额}
    E --> F
    F -->|无效或查询失败| G[展示异常并进入统一复位]
    F -->|0 元或大于 0| I[进入第三步卡片结算]
    I --> L{读卡区是否已有卡}
    L -->|是| L1[提示先拿走遗留卡片]
    L1 -->|检测到无卡| L2[等待新卡放入]
    L -->|否| L2
    L2 -->|新卡放入| M[读取完整卡片信息]
    M -->|0 元| H[跳过扣款并反馈携卡零元结果]
    H -->|反馈成功| J[零元完成]
    H -->|反馈失败| K[保存原请求待补传]
    M -->|大于 0| N[一卡通扣款]
    N --> O[后读卡]
    N -->|明确失败且实际扣款为 0| W[接口 C 反馈扣款失败]
    O -->|成功并校验通过| P[结束卡片保护窗口并反馈接口 C]
    P -->|反馈成功| Q[支付完成]
    P -->|反馈失败| R[扣款已完成，仅重试反馈]
    M -->|卡片移除或失败| S[确定未扣款，中断支付]
    N -->|卡片移除或结果不确定| T[禁止再次扣款，进入异常核对]
    O -->|卡片移除或失败| U[扣款可能已完成，禁止再次扣款]
    J --> V[WAITING_RESET：统一复位]
    G --> V
    K --> V
    Q --> V
    R --> V
    S --> V
    T --> V
    U --> V
    W -->|上传成功或失败已落库| V
    V -->|复位条件满足并释放锁盘| A

8. 页面需求

8.1 第一步：等待放盘

页面目的

明确告诉用户把餐盘放到识别区，并等待系统自动识别。

页面内容

• 主标题：请放置餐盘
• 辅助说明：请将餐盘平稳放入识别区域
• 餐盘放置示意图，沿用或优化当前放盘页面素材。
• 必要的设备异常提示区域；正常状态不展示调试信息、串口信息或接口明细。

交互规则

1. 页面打开后持续等待有效餐盘码。
2. 无效码、空码或瞬时抖动不切页，可短暂提示“未识别到有效餐盘，请重新放置”。
3. 识别到有效餐盘后立即创建餐盘会话、锁定餐盘识别，并自动切换第二步。
4. 同一餐盘重复上报不得创建第二个会话或重复请求订单。
5. 上一笔订单未安全结束时，即使检测到新餐盘，也不得覆盖上一笔订单。

8.2 第二步：获取订单并判断金额

页面目的

让用户知道系统正在确认订单，并展示最终订单号和金额。

请求中状态

• 主标题：正在获取订单
• 辅助说明：正在根据餐盘信息查询待结算订单
• 查询过程中不展示任何引导用户拿走或保留餐盘的提示。
• 展示加载动效，不展示“支付”按钮。

餐盘在请求中被拿走

1. 不取消订单请求，不返回第一步。
2. 记录 tray_removed = true，页面改为：餐盘已取走，正在继续确认订单。
3. 保持锁盘，不处理其他餐盘识别结果。
4. 请求返回后继续校验订单号和金额，并进入对应分支。

订单成功状态

• 展示订单号。
• 展示人民币格式金额；内部和接口始终使用分单位整数。
• 不展示用户需要理解的接口码、原始 JSON 或读卡原始数据。

金额判断

零元读卡与完成

• 页面提示 本单金额为 0 元，请放卡核验，读取过程中提示 零元核验中，请勿移动卡片。
• 仅读取一次完整卡片信息，不调用扣款、钱包规划或任何写卡指令。
• 读卡失败不调用接口 C；用户移卡后继续等待下一次放卡。
• 接口 C 成功：显示 结算完成，请取走卡片和餐盘。
• 餐盘已拿走：完成提示短暂展示后自动回到第一步。
• 餐盘未拿走：保持完成页，直到检测到餐盘拿走，再回到第一步。
• 接口 C 失败：本地保存携带本次卡信息的原始请求；页面提示 结算结果正在补传，不得重新读卡或扣款。

订单查询异常

8.3 第三步：卡片结算

页面目的

引导用户放置卡片。零元单完成只读核验，正金额完成一卡通支付；卡片处理期间清晰说明不可移卡。

进入页面

• 正金额主标题及语音：请放卡片进行支付
• 零元主标题：本单金额为 0 元，请放卡核验；不播放带“支付”含义的语音。
• 展示订单金额，订单号弱化展示。
• 页面不根据餐盘是否已拿走展示不同引导；餐盘状态只用于内部会话管理和终态复位。
• 辅助提示：请将卡片平放在读卡区域。
• 不出现“请刷卡”“点击支付”或可重复触发扣款的按钮。
• “请放卡片进行支付”语音每个订单会话只播放一次；页面重建、前后台切换或读卡器重连不得重复播报。

等待卡片

1. 当前订单完成金额判断后均允许武装一次卡片流程；零元仅获得读卡执行权，正金额获得扣款执行权。
2. 同一订单同时只能存在一个卡片硬件任务。
3. 进入第三步时必须先确认读卡区为无卡状态；若已检测到卡片，页面提示 请先拿走卡片，此时禁止读卡和扣款。
4. 检测到无卡后才进入“等待新卡”状态；只有随后发生的新放卡事件才能开始本订单交易。
5. 等待新卡设置可配置安全超时。超时发生在扣款指令发送前，可安全取消本次支付：餐盘已拿走时展示结果后复位；餐盘仍在时保持超时状态，待餐盘拿走后复位。
6. 超时后不得在原会话中自动重新寻卡。管理员可结束仍未扣款的超时会话，但不能结束已经发出扣款指令的会话。

零元只读卡

1. 检测到新卡后执行一次完整 readCard，保存卡片身份、余额和消费次数。
2. 不执行补贴/主钱包规划，不调用消费接口，不产生 PSAM/TAC。
3. 反馈协议中的 before_card_info 与 after_card_info 使用同一真实读卡快照；这是无写卡场景的协议镜像，不代表发生了第二次物理读卡。
4. 读卡失败时只记录失败，不发送成功反馈；移卡后回到等待新卡状态。
5. 读卡成功后结束卡片保护窗口，接口 C 反馈可在用户取卡后继续。

交易中

页面固定展示：

• 主提示：支付处理中，请勿拿走卡片
• 阶段提示按实际步骤变化：
  1. 正在读取卡片信息
  2. 正在进行扣款
  3. 扣款完成，正在确认卡片余额
  4. 卡片读取完成，正在确认结算结果

交易开始后隐藏或禁用所有可能重新发起支付的控件。餐盘在此阶段拿走不取消交易，只记录状态用于完成后的页面收尾。

后读卡完整成功并通过卡片一致性、金额及余额校验后，卡片保护窗口结束，页面改为 卡片读取完成，可拿走卡片。随后接口 C 的网络反馈可在卡片已经拿走的情况下继续，不得因移卡取消反馈或把反馈失败误判成扣款失败。

支付成功

只有以下条件全部满足，页面才能显示“支付成功”：

1. 前读卡成功。
2. 所有计划扣款段完整成功，实际扣款总额等于本次计划金额。
3. 后读卡成功。
4. 接口 C 返回业务成功 code = 0。

成功文案：支付成功，请拿走卡片。卡片拿走后：

• 餐盘已经拿走：回到第一步。
• 餐盘仍在：提示 请拿走餐盘，餐盘拿走后回到第一步。

扣款成功但反馈失败

• 页面：扣款已完成，结算结果正在补传，请勿再次支付。
• 本地交易状态标记为 DEBITED_REPORT_PENDING。
• 只能使用原订单号和原三阶段数据重试接口 C，禁止重新查询后再次扣款。
• 无论接口调用失败、超时、响应无法解析还是服务端返回业务失败，前台都继续进入统一复位；卡片和餐盘都拿走后可返回第一步，但补传任务必须在后台保留，应用重启后继续。

9. 餐盘行为规则

锁盘释放条件：订单进入安全终态，且页面已经完成当前结果展示。单纯检测到餐盘物理移走不能提前释放锁盘。

锁盘范围是完整餐盘会话，而不只是订单查询阶段。即使订单金额已经判断完成，只要支付、反馈、异常落库或统一复位尚未达到安全条件，就不得接收下一只餐盘建立新会话。

10. 卡片中途移除与失败矩阵

10.1 基本原则

1. 检测到新卡并开始前读卡后进入卡片保护窗口；窗口内任一步检测到卡片移除，都停止尚未开始的后续动作。
2. 已经发送的硬件指令不能通过 UI 强行撤销。
3. 只要存在“可能已经扣款”，当前订单就永久禁止自动再次扣款，直到人工或可靠数据确认。
4. 页面必须提示具体失败阶段，不能统一显示“支付失败”。
5. 后读卡完整成功并通过客户端校验后，卡片保护窗口结束；此后用户拿走卡片不影响接口 C 反馈。
6. 前读卡失败、提前移卡、余额不足或扣款前硬件断开属于扣款前失败，只记本地，不调用接口 C。
7. 只有扣款指令已经返回明确失败且能确认实际扣款金额为 0，才作为“扣款明确失败”调用接口 C。
8. 零元单读卡失败没有写卡风险，移卡后允许在同一订单会话继续等待下一次放卡；没有完整卡信息时禁止反馈零元成功。

10.2 分阶段处理

10.3 前后读卡与扣款校验

接口 C 服务端不校验前后卡片是否属于同一人员，也不校验反馈扣款金额是否等于订单金额，因此客户端在显示成功和调用成功反馈前必须完成：

1. 前后读卡的 uid、customerID、cardNO、cardASN 分别一致；任何关键身份字段缺失或不一致，都不得按成功处理，进入 DEBITED_VALIDATION_FAILED 并禁止再次扣款。
2. 所有已完成钱包扣款段的金额合计必须等于订单金额；不相等时进入部分扣款或异常核对状态。
3. 根据一卡通协议校验消费前后钱包余额和消费计数变化，与实际完成的各段扣款一致。
4. 校验使用结构化字段，不依赖页面文本或日志字符串；校验失败原因写入本地交易记录。

10.4 餐盘状态联动

• 卡片中断时餐盘未拿走：页面保持对应异常状态，不自动重新支付；检测到餐盘拿走后完成本轮收尾。
• 卡片中断时餐盘已拿走：保存完整本地记录，展示对应异常结果后返回第一步。
• 返回第一步不等于异常已解决；后台补传或人工核对任务继续存在。

11. 一卡通钱包规则

1. 订单金额单位为分，必须使用整数计算。
2. 扣款顺序为补贴钱包优先、主钱包补足。
3. 补贴足够时只产生一段补贴钱包交易。
4. 补贴不足但总余额足够时，先扣尽所需补贴金额，再从主钱包扣剩余金额。
5. 补贴为零时只扣主钱包。
6. 总余额不足必须在发送第一条扣款指令前拒绝，页面显示 卡内余额不足。
7. 多钱包部分成功不能按整单成功展示，也不能自动从头重试。

12. 接口需求

12.1 接口 B：按餐盘查询待结算订单

• 方法与路径：POST /api/oneCardTerminal/acquireByPlate
• Content-Type：application/json
• 请求：
  • plate_code：餐盘码。
  • equipment_code：设备编号。
• 响应关键字段：
  • order_no：订单号。
  • amount：订单金额，单位分。

客户端要求：同一餐盘会话只允许一个有效请求；换盘或页面销毁后的迟到响应不得覆盖新会话。订单号是服务端生成的唯一业务标识，接口 B 按其既有定义只返回待结算订单；本期不增加跨设备并发结算设计。

12.2 接口 C：反馈一卡通扣款结果

• 启用条件：系统配置 meal_model = 4。
• 方法与路径：POST /api/oneCardTerminal/report
• Content-Type：application/json
• 顶层字段：
  • order_no
  • equipment_code：必填，使用餐盘会话开始时锁定的当前设备编号。
  • settlement_result
  • before_card_info
  • after_card_info

零元订单

{
  "order_no": "订单号",
  "equipment_code": "设备编号",
  "settlement_result": {
    "code": 0,
    "amount": 0
  },
  "before_card_info": { "customerID": 29373, "cardNO": 1705827, "...": "完整读卡字段" },
  "after_card_info": { "customerID": 29373, "cardNO": 1705827, "...": "与前读卡相同" }
}

• 设备只物理读卡一次，不发送扣款或写卡指令。
• before_card_info 与 after_card_info 镜像同一真实快照，两个对象都不得为空。
• settlement_result 不携带 psamID、psamJyNo、tac。
• 接口 B 与接口 C 必须使用同一餐盘会话锁定的 equipment_code；接口 C 入队后，后台补传复用原始请求中的设备编号，不重新读取配置。

正金额成功订单

• settlement_result.code = 0。
• settlement_result.amount 为实际扣款总额。
• before_card_info 为消费前完整读卡信息。
• after_card_info 为消费后完整读卡信息。
• 多钱包时 psamID/psamJyNo/tac 取最后一段成功交易。

扣款明确失败

• 仅适用于扣款指令已经返回明确失败，且能够确认实际扣款金额为 0 的情况。
• settlement_result.code 使用一卡通返回的非零失败码，message 使用实际失败原因，amount = 0；不得编造失败码或用接口上传错误替代交易失败码。
• 已取得完整前读卡时传入原 before_card_info，没有可用前读卡信息时传空对象 {}。
• 未完成后读卡时 after_card_info 传空对象 {}。
• 前读卡失败、提前移卡、余额不足和扣款前硬件断开不属于扣款结果，不调用接口 C。
• 部分扣款、扣款结果不确定、后读卡失败和前后卡身份不一致不提交通用失败结果，只保存本地异常并禁止自动再次扣款。

幂等和重试

1. 每次反馈必须携带原始 order_no。
2. 接口超时或失败不代表扣款失败。
3. 本地已经记录扣款成功时，只能重试原反馈，不得再次扣款。
4. 服务端对已成功反馈订单重复收到成功结果时应幂等返回成功。
5. 服务端业务成功以响应体 code = 0 为准，不能只判断 HTTP 状态。
6. 接口 C 的上传结果不作为前台放行条件；上传成功时标记完成，上传失败时可靠落入补传队列，两种情况都继续当前订单的结果展示和统一复位。
7. “上传失败”包括网络不可用、请求超时、HTTP 失败、响应解析失败和服务端业务 code != 0；以上情况必须保存最近失败原因，但不得重新扣款或阻塞下一笔订单。
8. 同一订单出现重复上传，只能来自首次上传未确认成功后的补传；必须使用相同 order_no 和原始请求快照，不创建新订单号或新结算记录。
9. 服务端已经确认相同订单的成功反馈具备幂等处理；订单号相同是识别同一笔反馈的业务键，本期不再把重复上传列为待确认项。

交易失败与上传失败边界

• 一卡通交易失败描述的是扣款动作本身的结果，接口 C 上传失败描述的是结算结果没有成功送达服务端；两者不得共用一个状态或错误码。
• 扣款明确失败可以形成接口 C 失败请求；接口 C 上传失败只保存该请求快照并进入补传队列。
• 补传再次失败只增加反馈尝试记录，不改变原一卡通交易结果，也不允许重新扣款。
• 前台页面只展示用户可理解的交易结果；上传失败统一表达为“结算结果正在补传”，不展示 HTTP 或服务端技术错误。

13. 本地记录与可靠补偿

13.1 记录要求

每笔订单建立一条可持续更新的本地交易记录，至少包含：

• 本地记录 ID、订单号、餐盘码、设备编号。
• 订单金额、订单响应时间和订单接口摘要。
• 餐盘识别时间、餐盘移除时间及是否提前移除。
• 前读卡完整结构、原始响应摘要、成功或失败时间。
• 每段钱包扣款：钱包类型、金额、扣款前后余额、消费计数、PSAM 信息、TAC、阶段状态。
• 后读卡完整结构、原始响应摘要、成功或失败时间。
• 接口 C 请求快照、反馈次数、最近反馈时间、响应码、响应消息、trace_id。
• 当前业务状态、失败阶段、是否禁止再次扣款、创建和更新时间。
• 一条订单级结算汇总记录，以及其下每次查询、读卡、扣款和反馈尝试的子记录；禁止把一次重试当成新的结算记录。

13.2 写入时机

1. 获取订单成功后立即创建记录。
2. 每完成一个硬件阶段立即更新，不等待整笔流程结束。
3. 扣款指令发送前写入“即将扣款”的事务标记；结果返回后立即更新为成功、失败或不确定。
4. 调用接口 C 前保存完整请求快照，确保网络失败或应用重启后能原样重试。
5. “即将扣款”事务标记必须成功持久化后才能向硬件发送扣款指令；落库失败、磁盘空间不足或数据库不可用时立即停止支付并提示联系工作人员。

13.3 补传队列

• 零元反馈失败和正金额成功反馈失败都进入持久化补传队列。
• 补传调度器每 3 分钟唤醒一次；应用启动或网络由不可用恢复为可用时可额外立即触发一次。
• 每批按记录创建时间从旧到新最多读取 50 条；第一批结束后仍有到期记录且网络正常时，间隔 3～5 秒继续第二批。
• 单轮最多执行 2 批，即最多处理 100 条；超过部分留到下一轮，禁止无上限全量提交。
• 批大小 50、单轮批次上限 2 和批间隔 3～5 秒应作为系统配置提供，以上数值为默认产品参数。
• 同一时间只允许一个补传任务运行；定时器、应用启动和网络恢复同时触发时必须合并，不能创建并行同步轮次。
• 单条失败不得中断本批其他记录；记录失败次数、最近失败原因，并默认设置为下一个 3 分钟周期可再次同步。
• 同一订单的反馈严格串行；不同订单最多允许 3 条低并发上传，并发数必须可配置，默认值为 3。
• 应用重启、网络恢复或设备重新上线后继续处理。
• 正金额补传只重放接口 C 请求，绝不重新调用一卡通扣款。
• 服务端确认成功后标记 REPORTED，停止重试并保留审计记录。

13.4 应用重启恢复矩阵

恢复判断只能依据已持久化事务记录，不能依据 Activity、Fragment、内存标志或语音播放状态。

13.5 数据安全

• 不保存一卡通密钥、Access Token、人脸特征或无业务必要的敏感数据。
• 日志中订单号、卡号等字段应按项目日志规范脱敏。
• 本地记录保留周期和最大容量由配置控制；超过周期时优先清理已成功反馈记录，未完成补传和异常核对记录不得自动删除。
• 当未完成补传或异常核对记录导致存储空间低于安全阈值时，停止新订单扣款并告警，不得通过自动删除这些记录换取空间。

14. 状态机

任何带 DEBITED、PARTIAL_DEBIT 或 DEBIT_UNKNOWN 的状态都必须设置 debit_retry_forbidden = true。WAITING_RESET 只有在本地终态记录落库成功、最短展示时长已满足、卡片不处于保护窗口且需要清场的卡片/餐盘已移除后，才能释放锁盘并进入 WAITING_TRAY。

15. 页面文案与语音清单

首次完整读卡成功后，第三步原页面显示持卡人、补贴余额和现金余额。首次快照标记为读卡时余额，零元标记为卡片余额，正金额完整成功后更新为结算后余额。

所有用户可见文案避免“刷卡”“技术错误码”“APDU”“PSAM”等技术词汇。管理员诊断入口可查看详细阶段和错误码，但不在主流程页面展示。

16. 防重复与并发要求

1. 同一时刻只能存在一笔前台餐盘会话和一笔卡片硬件交易。
2. 餐盘识别、订单请求、支付执行和结果反馈均使用订单会话 ID 隔离迟到回调。
3. 同一订单号本地已有 COMPLETED、DEBITED_REPORT_PENDING、PARTIAL_DEBIT 或 DEBIT_UNKNOWN 时，不得再次扣款。
4. 卡片持续放在读卡区时只能触发一次交易；必须检测到移卡并进入下一笔有效订单后才能再次交易。
5. 页面重复创建、横竖屏变化、应用切后台或网络重连不得重复发起扣款。
6. 断电或崩溃恢复时先检查本地事务记录，再决定继续反馈、进入人工核对或允许新订单。

16.1 页面生命周期与设备异常

1. 扣款指令发送前，用户离开页面或管理员结束会话只能执行安全取消，并先持久化取消结果。
2. 开始前读卡后禁用普通返回、重复进入其他业务页和普通退出；只有受控管理员入口可以查看状态，不得销毁交易会话。
3. Activity/Fragment 重建、横竖屏、切后台或进程内页面跳转只重建展示层，订单状态机和硬件任务必须由独立于页面的会话层持有。
4. 扣款指令发送后发生 USB 断连、读卡器掉线、硬件回调丢失或应用异常退出，一律记为 DEBIT_UNKNOWN，禁止再次扣款。
5. 页面销毁不得取消已经发出的硬件指令，也不得删除已保存的接口 C 请求快照或补传任务。
6. USB 在扣款前断开时可确定未扣款并安全结束；USB 恢复后不得自动沿用旧订单寻卡或发起扣款。

16.2 运行监控与容量保护

• 设备至少上报：待补传数量、最老待补传时长、异常核对数量、最近一次补传结果、本地存储剩余空间和最近一次硬件断连。
• 补传监控同时记录每轮触发来源、读取条数、成功条数、失败条数、跳过条数、耗时、剩余积压量和是否达到单轮 100 条上限。
• 待补传、结果不确定、部分扣款和校验失败达到配置阈值时告警工作人员。
• 未完成补传或异常记录不得自动删除；存储空间进入保护阈值时暂停新扣款，但仍允许补传和管理员导出诊断信息。

17. 验收标准

17.1 主流程

• 放盘识别成功自动进入订单页，同一餐盘只请求一次订单。
• 查询期间拿走餐盘，请求继续且新餐盘不能覆盖当前订单。
• 零元订单必须等待新卡并完整读卡一次，不执行扣款；接口 C 前后卡字段携带同一真实快照。
• 正金额订单自动进入第三步，页面和语音均使用“请放卡片进行支付”。
• 订单成功后不展示“订单已确认”或“正在进入支付/核验”，直接进入第三步。
• 第三步进入时若读卡区已有卡，必须先提示拿走；只有检测到无卡后的新放卡事件才能开始交易。
• 完整执行前读卡、扣款和后读卡；真实后读卡校验通过后显示结算完成，接口 C 继续反馈，失败时按原请求后台补传。
• 首次完整读卡后立即显示持卡人、补贴余额和现金余额；正金额成功后更新为真实后读卡余额。
• 前读卡、扣款、后读卡和接口反馈在页面上合并为一个处理中状态，业务记录仍能区分全部阶段。
• 双钱包扣款金额合计准确，接口凭证取最后一段成功交易。
• 后读卡及客户端校验成功后允许拿走卡片，接口 C 反馈继续且不依赖卡片仍在。

17.2 异常流程

• 订单查询失败、金额异常、设备未配置均不能进入扣款。
• 前读卡、扣款、后读卡任一阶段拿走卡片，页面能准确提示中断阶段。
• 前读卡失败、提前移卡、余额不足和扣款前硬件断开只保存本地记录，不调用接口 C。
• 零元单读卡失败不反馈成功，移卡后继续等待下一次放卡；读卡成功后才允许入队并上传接口 C。
• 扣款指令返回明确失败且实际扣款为 0 时，按失败格式调用接口 C；上传失败进入补传且不阻塞复位。
• 扣款指令发送后出现异常，系统不自动再次扣款。
• 部分钱包成功时页面保留真实成功金额，不显示整单完全成功或完全未扣款。
• 扣款成功但反馈失败时，拿走卡片和餐盘后可开始下一单，同时后台只补传原结果。
• 零元单和正金额单调用接口 C 时，无论上传成功还是失败，前台均能完成结果展示并进入统一复位；失败请求已可靠落库。
• 应用重启后待反馈任务仍存在，网络恢复后能够继续补传。
• 等待新卡超时只能在未扣款时安全结束，不得因超时取消已发送的扣款或自动重试。
• 扣款指令发送后 USB 断连、进程退出或回调丢失均进入结果不确定状态并禁止重扣。

17.3 数据与接口

• 一笔订单的订单信息、零元读卡或正金额三阶段结果、反馈请求和响应能够通过订单号关联查询。
• 前后卡关键身份一致，扣款段合计等于订单金额，余额和消费计数变化校验通过后，才允许提交成功反馈。
• 接口 C 重复提交不会产生重复订单完成或重复扣款。
• 同一订单补传使用相同订单号和原请求快照；补传只增加反馈尝试记录，不创建新的结算记录。
• 定时补传每 3 分钟触发，每批最多 50 条、单轮最多 2 批共 100 条；单条失败不会阻塞本批后续记录。
• 定时、应用启动和网络恢复同时触发时只运行一个同步轮次；第一批仍有积压时按规则继续第二批，不进行无上限全量同步。
• 未反馈成功、部分扣款和结果不确定记录不会因普通日志清理而丢失。
• 主页面不展示或记录不必要的敏感信息。

17.4 设备验收

• 使用真实餐盘扫码器验证放盘、移盘、连续换盘和重复上报。
• 使用测试卡验证补贴足够、补贴不足、主钱包支付、余额不足、卡片中途拿走。
• 验证断网、接口超时、服务端业务失败、网络恢复、应用重启，以及 50/51/100/101 条待补传记录的批次边界。
• 验证遗留卡片、新卡入场、等待超时、页面重建、切后台、USB 断连和本地存储不足。
• 验证语音清晰度、播放时机以及语音开关。

18. 产品补充建议

以下内容是为保证业务完整性补充的默认方案，若后续没有相反确认，原型和技术方案按此执行：

1. 取消主流程支付按钮，订单金额判断后自动进入第三步。
2. 订单查询和结果反馈使用持久化状态，不依赖 Activity 是否存活。
3. 反馈失败允许页面复位，但必须保留后台补传任务。
4. 结果不确定、部分扣款和扣款后复读失败不允许普通用户重试，后续应提供管理员异常处理入口。
5. 页面以用户动作和结果为主；接口码、读卡原始数据和交易阶段明细放入管理员诊断或本地记录。
6. 新卡入场校验、扣款前持久化闸门、前后卡身份校验和统一复位状态属于支付安全底线，不作为可选配置关闭。
7. 订单查询期间到统一复位完成前持续锁定餐盘会话；餐盘拿走只影响收尾条件，不释放业务锁。

19. 待后续专项确认

以下事项不阻塞方案 B 定稿与主流程开发，但会影响最终运维和异常处置范围：

1. 对 DEBIT_UNKNOWN、PARTIAL_DEBIT、DEBITED_AFTER_READ_FAILED 的后台人工处理入口由哪个系统提供。
2. 补传连续失败的告警阈值和管理员处置方式；同步周期、批量及单轮上限已经确认。
3. 成功、失败结果在餐盘和卡片均已拿走后的最短展示时长。
4. 本地交易记录的具体保留天数和设备容量上限。
5. 是否增加支付成功、异常提示音；“请放卡片进行支付”语音为必需。

20. 原型设计输入

原型必须至少覆盖以下可切换场景：

1. 第一步等待放盘。
2. 第二步正常查询订单。
3. 第二步查询时餐盘已拿走。
4. 零元订单等待放卡、读卡中、反馈中、成功、读卡失败重试和补传中。
5. 正金额订单自动进入第三步，分别覆盖餐盘仍在和餐盘已拿走两种状态，但页面文案保持一致。
6. 第三步等待卡片。
7. 前读卡、扣款、后读卡、反馈四个处理中状态。
8. 支付成功。
9. 卡片在三个硬件阶段分别被拿走。
10. 部分扣款、结果不确定、后读卡失败、反馈失败。
11. 餐盘未拿走时保持结果，以及餐盘已拿走时自动复位。
12. 进入第三步时读卡区已有卡、读卡区清空、重新放入新卡三个状态。
13. 等待新卡超时、后读卡完成后允许移卡、统一复位和 USB 断连状态。

原型视觉需延续绑盘页面的三步结构、标题区、主插画和大字号提示，但不能照搬当前消费调试面板。主流程只保留用户需要理解的信息，详细订单和硬件数据通过管理员诊断入口查看。

21. 评审结论

• 已确认：三页结构、自动切页、金额判断、零元读卡核验及携卡反馈、正金额三阶段成功反馈、餐盘行为中性且提前移除不中断、卡片中途移除中断、多钱包凭证规则、不处理 Access Token。
• V0.9.2 已补齐：新卡入场、卡片保护窗口、等待超时、客户端交易校验、扣款前持久化闸门、重启恢复、页面生命周期、USB 断连、运行监控和统一复位状态。
• V0.9.3 已确认：接口 C 上传结果不阻塞前台；失败请求持久化后每 3 分钟补传，每批 50 条、每轮最多 2 批共 100 条，并支持启动/网络恢复触发和同步任务防重。
• V0.9.4 已确认：扣款前失败不调用接口 C；扣款明确失败按失败格式反馈；部分扣款和结果不确定只保存本地异常；上传失败只补传原请求；订单号是补传幂等业务键；本期不增加跨设备并发结算设计。
• V0.9.5 已确认：零元单不再直接反馈；必须读取一次完整卡片信息且不执行扣款，前后卡字段镜像同一快照；读卡失败移卡后可重试，反馈失败只补传首次落库请求。
• V0.9.6 已确认：保留三步但取消订单成功过渡页；第三步将内部读卡、扣款、复读和反馈合并为少量展示状态；首次读卡显示持卡人及补贴/现金余额，完整成功后更新真实结算后余额；统一更换为同色系操作配图。
• 原型评审结论：采用方案 B“金额聚焦型”作为最终视觉方案，A/C 保留为探索证据，不进入生产实现。
• 当前状态：V0.9.6 已进入 Android 代码落地，等待真机视觉与流程验收。