离线订单补传链路改造记录

• 日期：2026-10-09
• 项目：AIDishRecognition
• 范围：刷卡、人脸支付的 MQTT 离线记账及 HTTP/MQTT 订单补传
• 状态：客户端代码和本地构建验证完成；服务端幂等与设备联调待确认

本次变更

• 人脸识别的 User.userId 对应服务端 staff_uuid，离线订单保存到 consumer_uuid；HTTP 和 MQTT 补传均复用该值。
• 首次请求生成的 msgid、设备号和消费时间随订单持久化；补传不再用当前设备号重新拼接交易标识。
• 离线模式下，刷卡与人脸 MQTT 请求发送前先落库为上传中。回包、超时、进程重启分别确认完成、恢复待传或保留待核对状态。写库失败不向界面报离线记账成功。
• 数据库升级增加原始交易标识、原始设备号、上传时间和最近失败原因。旧版未完成订单缺少原始标识，迁移到待人工核对，不自动猜值补传。
• 自动和手动补传共用数据库条件领取状态；上传中订单超时恢复，迟到成功按原始 msgid 确认，已完成订单不会被失败或超时降级。
• HTTP Worker 同步等待响应，按服务端结果回写状态；MQTT 补传等待订阅就绪，发布失败释放订单，业务回包决定完成状态。两种方式共用菜品和人员字段组装。
• 注册闹钟接收器，收到轮询信号先预约下一轮；唯一 HTTP Work 避免重复启动，15 分钟 WorkManager 周期任务提供持久兜底。手动补传按当前提交模式路由。
• 订单详情展示状态、原始交易标识和最近补传原因。

验证

• ./gradlew :app:testDebugUnitTest :app:assembleDebug --offline：通过。
• 新增 OfflineOrderUploadPolicyTest，覆盖人脸 UUID、原始交易标识、订单状态和可重试响应准入。
• git diff --check：通过。

边界与联调项

• 本地 Store 源码存在按 msgid 查询已有订单的逻辑，但部署版本及并发唯一约束尚未确认。需以实际服务端验证同一 msgid 重传只记账一次、重复请求返回原订单结果，以及跨日重传沿用原始 create_time 的行为。
• 仍需目标设备验证断网、进程被杀、开机恢复、设备重新绑定、MQTT 迟到回包、手动与自动同时触发等场景；本地构建不能替代端到端验收。
• 迁移后的旧待传订单需要人工核对原交易标识与人员 UUID，确认服务端账务后处置；客户端不会自动重传这些订单。

文件与操作

• 业务源码、资源、清单、数据库结构和单元测试已在 AIDishRecognition 仓库修改。
• 本记录仅保存在提示词工程，Markdown 与同名 HTML 同步。
• 未安装 APK，未执行 Git 提交、推送或分支操作。