Requirement analysis · V0.1

450 双秤设备
取餐数据可靠上传

把“偶尔上传不到”从不可复现的现场问题,转化为可恢复、可幂等、可追踪、可验收的端到端能力。

2026-07-29设备类型 4WeightDouble116待联合评审

先说结论

这不是“多重试几次”的需求。只改设备重试,会在“服务端已经写入、设备没收到响应”时造成重复入账。完整方案必须同时包含:设备端先落库、稳定事件号、可靠补传、服务端幂等、原子事务和端到端观测。
0
目标静默丢单数

每条有效取餐必须成功,或留下明确可处理的失败状态。

99.9%
断网恢复后 10 分钟内补传

建议目标,取得现网基线后再最终确认。

0
重复业务入账数

相同事件重复请求,只能返回“已处理”,不能再次累计金额。

代码与资料确认

  • 事实 450 对应 WeightDouble116 双秤,设备类型为 4
  • 事实 左右餐台各自产生取餐数据,上传结果会影响其他秤看到的累计金额。
  • 事实 当前业务入账使用 /p/api/zhctPushMeal
  • 缺口 现有服务端代码未见设备业务事件唯一号,不能安全支撑盲目重试。
  • 边界 当前工作区没有 450 Android 源码,设备端现状需开发补充确认。

最可能的故障位置

  1. 取餐后先请求、未先落库,页面或进程变化使任务消失。
  2. 断网、超时、切后台后没有持久化补传任务。
  3. 左右秤快速交错时,共用对象或回调覆盖数据。
  4. 服务端返回业务失败,设备未正确分类处理。
  5. 服务端已写入但响应丢失,设备无法判断,重试会重复入账。

目标链路

01 · 结算左/右秤完成一次有效取餐,生成独立 session。
02 · 落库生成稳定 event_id,完整快照先写入 SQLite。
03 · 调度唯一后台任务按发生时间串行上传。
04 · 幂等服务端按 device_code + event_id 原子处理。
05 · 闭环成功删除/归档;临时失败退避;永久失败告警。

设备端 P0

  • 先落库再上传;落库失败不能展示成功。
  • 事件号首次生成后,所有重试保持不变。
  • 应用启动、网络恢复、新事件入库都进入同一调度器。
  • 断网、超时、5xx 退避重试;业务永久失败停止重试并告警。
  • 左/右秤写入独立 scale_code 和 session,禁止共享可变请求对象。
  • 设置页显示待传数、永久失败数、最老积压时间和最近成功时间。

服务端 P0

  • /p/api/zhctPushMeal 兼容新增 event_id、scale_code、app_version。
  • 数据库增加 device_code + event_id 唯一约束。
  • 事件校验、明细写入、订单金额累计在同一事务中。
  • 重复事件返回成功且 duplicate=true,不再次入账。
  • 明确 retryable 与 non-retryable 响应,不再混用非零 code。
  • 按事件号、设备、左右秤、餐盘和时间支持查询。

状态模型

状态含义系统动作
PENDING已落库、待上传进入唯一调度队列
UPLOADING正在请求服务端进程重启后恢复为待处理
RETRY_WAIT网络、超时或 5xx保留数据,按退避时间再次上传
SUCCESS首次成功或服务端确认重复停止上传,按保留策略归档
TERMINAL_FAILED参数或永久业务失败停止自动重试,展示原因并告警

验收门槛

断网断网连续取餐 10 次,重启设备后恢复网络,10 条均在 10 分钟内补传。
响应丢失服务端入账后故意丢弃响应,设备重试但服务端只保留一条明细和一次金额累计。
双秤并发左右秤 1 秒内同时结束取餐,生成两个不同事件号,均正确入账。
进程退出落库后、发请求前杀掉 App,重启后仍能自动继续。
永久失败餐盘未绑定等明确错误不无限重试,设备和后台均可查失败原因。
高峰压测500 条事件、5% 模拟超时,无丢失、无重复入账,队列最终清零。

范围与版本

V1 · 一个迭代

设备端持久化与补传、服务端幂等事务、基础状态查询和告警、真机弱网验收。

V1.1 · 运营增强

PC 上传记录页、永久失败人工处理、设备版本覆盖率和积压趋势。

本期不做

不重做称重算法;不扩展完整离线支付;不直接用重量事件接口替代业务入账。

灰度门槛

1–2 台设备先灰度,覆盖至少 3 个用餐高峰和一次人为断网恢复,无丢单、无重复、无积压后扩面。

评审前必须补齐

  1. 现场设备号、App 版本、发生时间、左右秤、餐盘号后几位。
  2. 450 当前源码中的本地表、上传调用顺序、重试机制和日志格式。
  3. 餐盘未绑定、菜品不存在、人员删除分别是否允许后续自动恢复。
  4. 断网时是否允许继续取餐;成功记录本地保留 7 天还是 30 天。
  5. 灰度项目、设备清单和产品、研发、测试、运维负责人。