A02 / A03 防逃单报警技术业务全量说明

项目：ZhctWeightingTableYoukate
版本基线：2026-08-25 当前工作区代码
范围：A02 未放餐盘取餐与 A03 餐盘未绑定人员的触发、重量、页面、解除、认领补录、存储、上传、补传、同步、日志、异常和生命周期。

本文只描述当前客户端的实际行为；“现有实现边界”不是业务承诺，而是联调必须验证的技术事实。

1. 总体规则

  1. 同一时刻仅允许一个活动报警；报警激活后普通扫码和普通打餐被拦截。
  2. 管理卡必须先在页面选择，范围为 888880～888899。
  3. 放盘认领必须先选择，先本地保存再上传；常规成功解除要求服务端 code=0 且本地删除成功。
  4. 网络失败即时重试三次，仍失败进入 WorkManager 队列并提示累计可能暂未同步后解除。
  5. 业务失败、code=1、本地保存失败和本地删除失败均不能当作正常认领成功。

2. 关键数据与时间

项目A02A03
报警码A02A03
来源ANTI_ESCAPE_A02ANTI_ESCAPE_A03
页面重量本单逃单重量本单取餐重量
原餐盘号无sourceTrayCode

pickWeight = max(0, baselineWeight - currentWeight)。报警触发时间用于审计；本地 pick_record.pick_time 和服务端上传时间统一为认领人员确认、触发上传的当下时刻，不使用报警发生或 A03 原打餐开始时间。

3. 共用状态机

状态可响应输入结果
NONE无等待选择；A02 重量恢复可自动解除
WAIT_MANAGER_CARD有效管理卡解除
WAIT_TRAY_CLAIM六位非管理卡候选盘查人、保存、上传
LOCAL_SAVE_FAILED管理卡仅管理卡兜底

选择方式后等待 60 秒。超时和允许的返回选择回到 NONE，但报警本身不解除。同一持续餐盘只查一次，连续三帧空码后才可再次查询。

4. A02：未放餐盘取餐

触发与重量

仅在 A02 开关开启、打餐前、无盘、秤体稳定时检测。第一个稳定重量为基准；稳定减重达到配置阈值触发。报警期间无盘且稳定时重量实时更新，回到基准或更高时写 WEIGHT_RECOVERED 并自动解除，不补录、不上传。候选认领盘出现后冻结最后有效重量，避免盘重计入。

解除与认领

管理卡路径只解除并记录卡值，不生成取餐记录。认领路径查询 selectPlate；仅 code=0 且 staffInfo.uuid 非空有效。有效后用候选盘/人员、当前 A02 重量、当前上传触发时间和 alarmId 写入本地记录，再直传。

5. A03：餐盘未绑定人员

触发与重量

正常扫描盘后调用查人：code=0 但人员为空，或非零响应消息精确为“餐盘未绑定”时触发。原盘仍被识别、稳定且在打餐时，实时显示 max(0, 原盘进入打餐时重量 - 当前重量)。

实时重量页面与处理
0g仅全宽管理卡；不允许认领
>0g管理卡与放盘认领并排显示
从正数回到0g取消尚未执行的认领等待、隐藏认领入口；A03 不自动解除，仍须管理卡

两种路径

管理卡可在原未绑定盘仍在时解除，但不绑定该盘、不补录。认领只能在有重量时选择；选中后原盘不能被当作认领盘，连续三帧移走后冻结重量、切到打餐前且不执行普通 scanCodeResult(2)，所以不会生成空人员记录。之后放入的已绑定盘提供人员和盘号，原盘冻结重量作为补录重量。

6. 保存、上传与补传

结果本地记录报警结果
code=0 + 删除成功删除正常解除
code=0 + 删除失败保留并入队保持报警
code=1删除候选记录保持报警，要求绑定/换盘
业务失败保留并入队保持报警
网络失败三次保留并入队提示累计延迟后解除

保存最多三次；三次失败仅允许管理卡。Worker 对 A02/A03 都审计并补传；code=0 或 code=1 都沿用既有删除策略。

7. 累计同步、日志与边界

直传成功后，认领盘后续硬件回调会按正常流程重新查人刷新累计；Worker 成功时若当前正在该盘打餐，也会尝试刷新。日志包括报警日报警分类日志、local log 和网络请求日志；核心事件有 TRIGGER、ACTION_SELECT、PICK_WEIGHT_RECOVERED、SOURCE_TRAY_REMOVED、LOCAL_SAVE_ATTEMPT、UPLOAD_SUCCESS、NEED_TRAY_BIND、RESOLVE。

现有边界：Worker 对 A03 也会发布结果事件，但首页“补传成功后自动解除活动报警”的分支目前只匹配 A02。故 A03 在直传成功但删除失败、后续由 Worker 成功的情况下不会自动解除活动 A03；网络三次失败入队的分支不受此影响，因为它已当场离线解除。

另一个联调重点是 selectPlate 可查到人而 zhctPushMeal 返回 code=1 的服务端绑定不一致；客户端会保持报警，不能强制绕过。

8. 全量技术分支与异常口径

8.1 候选盘、查人和建单

  1. 候选盘必须为六位、非管理卡；没有先选择认领时，候选盘不进入查人，也不进入正常打餐。
  2. selectPlate 仅在 code=0 且 data.staffInfo.uuid 非空时视为成功。人员为空提示候选盘未绑定；非零返回提示查人失败；两者均保持报警，允许换盘。
  3. 补录表 pick_record 必须记录 picker_uuid、bar_code、pick_time、dish_uuid、dish_weight、source 与 alarm_id。菜品为空或重量小于等于 0 时保存失败。
  4. 本地插入最多三次。三次失败写 LOCAL_SAVE_FAILED，提示“取餐记录保存失败，无法进行放盘补录”，只保留管理卡异常兜底。

8.2 上传结果矩阵

直传结果记录处理报警处理
code=0且删除成功删除候选记录以 TRAY_CLAIM_UPLOAD_SUCCESS 正常解除
code=0但删除失败保留并调度 Worker保持报警，不能按成功解除
code=1按旧策略删除候选记录保持报警，记 NEED_TRAY_BIND，先绑定或换盘
其他业务失败保留并调度 Worker保持报警
网络、IO、超时、HTTP 5xx 或空响应，连续三次保留并进入 Worker提示累计可能暂未同步，以 TRAY_CLAIM_DEFERRED_NETWORK 解除

Worker 按 pick_id 升序补传，code=0 或 code=1 均沿用既有删除策略；其他结果或删除失败继续保留重试。报警补录不新增接口，仍调用 /p/api/zhctPushMeal。

8.3 生命周期与审计

触发时 MMKV 仅保存活动标记、类型、内容和触发时间。应用退出或进程中断会清空操作状态；重启发现未完成快照时写 PROCESS_INTERRUPTED 并清除快照，不能恢复实时重量、候选盘或已选择的处理方式。

日报警分类日志记录 TRIGGER、ACTION_SELECT、ACTION_CANCEL、ACTION_TIMEOUT、WEIGHT_RECOVERED、PICK_WEIGHT_RECOVERED、SOURCE_TRAY_REMOVED、保存/上传事件及 RESOLVE。每条可按 alarmId 串联；管理卡额外有 cardCode，认领额外有盘号、人员、记录 ID、pickTime 和服务端码。网络原始请求、响应和 trace_id 在网络日志中。

9. 验收重点

10. 代码定位

模块责任
HomeActivity触发、重量、状态机、查人、保存、上传、解除和日志
NoTrayPickDetector / TrayBindingAlarmPolicyA02 重量检测 / A03 精确触发
AntiEscapeAlarmDialogFragment锁屏、按钮、实时重量与状态提示
PickMealRecord / Worker本地待传记录、离线补传、审计
CPTNetworkRequestselectPlate 与 zhctPushMeal