一次领袋横跨用户端、业务 API、第三方任务或支付、设备桥接服务和实体机器。任何一步超时,都不能通过重复创建订单来“碰碰运气”,否则很容易造成重复出袋或重复结算。
完整流程
sequenceDiagram participant U as 扫码用户 participant A as 业务 API participant C as 支付 / 任务渠道 participant B as 设备桥接服务 participant D as 发袋设备 U->>A: 扫码并提交领袋请求 A->>A: 校验设备、位置、库存与领取资格 A->>C: 完成支付或任务验证 C-->>A: 返回可领取结果 A->>A: 创建订单和设备任务 A->>B: 请求向目标设备下发指令 B->>D: 发布出袋命令 D-->>B: 返回执行结果 B->>A: 上报任务回执 A->>A: 更新订单、库存与收益流水 A-->>U: 返回成功或可查询状态
资格校验
服务端至少需要检查:设备是否存在且已激活、最近是否在线、袋子余量是否充足、用户是否满足领取规则、任务或支付结果是否有效。地理位置可辅助阻止远程滥用,但不能替代设备身份和订单校验。
幂等与超时
为每次领取生成唯一业务单号,并用它贯穿订单、设备任务和回执。用户重复点击、第三方重复通知或设备重复上报时,系统返回已有结果,而不是再次发出命令。
设备执行具有不确定延迟。接口超时后,订单应进入“结果确认中”,由回执或补偿查询更新最终状态。只有收到明确失败且确认设备未执行,才允许重新下发。
库存与结算
库存扣减和收益入账应以可信的设备执行结果为依据,并保留流水。当前余量适合快速展示,库存流水才是排查“后台袋数与机器不一致”的依据。结算任务可以异步执行,但必须能通过业务单号追溯到原始领取记录。