人员同步一致性修复变更记录

日期：2026-09-24
项目：AIDishRecognition
范围：人员、卡片、人脸数据库、百度人脸索引、MQTT 与周期同步任务
Git 操作：未暂存、未提交、未切换分支

变更背景

原人员同步链路存在增量同步可能清空人脸库、部分失败仍反馈成功、客户与人脸职责混合、数据库与内存缓存/SDK 索引不一致、MQTT ACK 失败后重复落库、周期 Worker 自替换或旧任务覆盖新计划等问题。

本次修复以以下协议语义为准：

type=0 是增量同步，不执行 userClean()，空列表按成功且处理数为 0。
type=1 是全量快照，整批校验通过后原子替换；明确的空列表表示清空，缺失 data 或列表表示失败且不改库。
status=1/2 表示新增或更新，status=3 表示幂等删除。
/userdata 只维护客户/卡片数据，/facedata 只维护人脸特征数据。

已落地修复

人脸同步

新增进程级串行写协调器，HTTP、MQTT、心跳和定时任务共用同一人脸写入口。
performUpdate("0") 不再清库；增量新增/更新采用 UUID/数据库 ID 替换，删除采用幂等语义。
旧定时 Service 的 "0" 调用替换为命名协议常量，避免增量类型继续散落为魔法字符串。
全量数据先完成字段、Base64 和 512 字节特征校验，再在事务中替换 SQLite 数据。
FaceApi 的数据库与内存缓存同步更新；数据库写入失败时不污染缓存，读取结果使用防御性副本。
SDK 索引增删、重建与数据库变更在统一锁边界内执行，并记录已索引 ID，避免初始化重推与删除并发冲突。
同步结果统一统计成功、失败和跳过数量；任何单项失败都不会再上报整批成功。

客户与卡片同步

客户新增/更新改为按 UUID/ID 事务替换，状态 3 改为幂等删除。
全量客户同步先校验重复 UUID/ID，再执行单事务替换；空快照可清空，非法快照不改库。
卡片查询排除已删除状态，同时兼容历史 null/0 状态。
启动页增加响应体、data 和列表边界检查，并阻止页面销毁后的旧回调继续操作 UI、SDK 或导航。

MQTT 与周期任务

人脸 MQTT 改为异步等待真实落库/索引结果，仅完整成功后 ACK。
人员 MQTT 仅在数据库保存成功后 ACK。
消息状态采用 PROCESSING -> ACKING -> PENDING_ACK：ACK 失败后的重投只重试 ACK，不重复执行本地写入。
定时人脸同步和心跳 Worker 会真实等待回调；超时或失败最多重试 3 次，之后恢复下一正常周期。
循环任务使用两个固定 unique-work 槽位，并持久化 generation；重置后旧 Worker 无法覆盖新计划，也不会形成无界依赖链。
Worker 停止或超时后取消更新器并屏蔽迟到回调。

主要代码位置

app/src/main/java/com/cpt/aidishrecognition/sync/
app/src/main/java/com/cpt/aidishrecognition/utils/FaceDataUpdaters.java
app/src/main/java/com/cpt/aidishrecognition/manager/FaceSDKManager.java
app/src/main/java/com/cpt/aidishrecognition/mqtt/MqttSimple.java
app/src/main/java/com/cpt/aidishrecognition/workmanager/
app/src/main/java/com/cpt/aidishrecognition/dataabase/
datalibrary/src/main/java/com/example/datalibrary/api/FaceApi.java
datalibrary/src/main/java/com/example/datalibrary/db/DBManager.java
app/src/test/java/com/cpt/aidishrecognition/sync/

验收结果

执行：

./gradlew :app:testDebugUnitTest --rerun-tasks
./gradlew :app:assembleDebug
git diff --check

结果：

强制重跑 60 个 Gradle 测试相关任务，构建成功。
JVM 单元测试共 134 个，失败 0、错误 0、跳过 0。
Debug APK 构建成功，产物为 app/build/outputs/apk/debug/app-debug.apk。
git diff --check 无空白错误。
源码仓库中未新增 docs/、doc/ 或 prompt/ 文档目录。
独立规格与质量复审通过，未发现 P1/P2/P3 阻断项。

边界与后续设备验收

百度 SDK 使用全局内存索引且不提供完整枚举/清空接口；代码已通过进程内索引登记、旧数据库 ID 集合和数据库未命中自清理降低残留风险，最终仍需在真实设备上验证 SDK 返回码与重启恢复。
MQTT 消息状态为进程内缓存；进程重启后的服务端重投依赖 UUID 替换/删除的幂等语义。
建议真机补充验证：全量空快照、连续增量更新/删除、断网后 MQTT ACK 重投、Worker 超时/重启、SDK 初始化前后的索引一致性。

工作区说明

工作区原有菜品学习、识别及网络拦截器相关未提交改动，本次没有回滚、覆盖或纳入这些改动，也未执行任何 Git 写操作。