CusumptionMachine 启动同步合并方案

记录日期：2026-06-29；目标分支：fix_offline；适用范围：启动期人员同步、人脸库同步、离线缓存启动。

一、改造目标

启动期不再先同步人员、再额外请求一次人脸数据接口。以 syncUserInfoList(code, type) 作为唯一网络同步入口，把原人脸同步中缺失的删除、全量校准、FaceApi 更新能力补充到人员同步批处理里。

改造后启动链路收敛为：

syncUserList()
  -> syncUserInfoList(code, type)
  -> BatchCustomerSyncManager 保存业务人员表并维护 FaceApi
  -> 人脸 SDK/人脸 DB 初始化
  -> FaceSDKManager.initPush()
  -> FIRST_INIT_FINISH_TAG = true
  -> goMain()

二、全量和增量判定

继续沿用现有标记 FIRST_INIT_FINISH_TAG：

• false：首次初始化未完成，type = "1"，按全量处理。
• true：已完成首次初始化，type = "0"，按增量处理。

三、人员同步补齐规则

1. 业务人员表

• status = 3：按 staff_uuid 删除本地业务人员。
• status = 1/2 或其他非删除状态：按 staff_uuid 覆盖保存人员。
• 全量同步时，接口本次没有返回、但本地仍存在的人员，按 staff_uuid 删除。

2. FaceApi 人脸库

• status = 3：删除本地 FaceApi 中对应 staff_uuid。
• status = 1/2：本地已有则先删旧记录；有 feature 才添加新记录。
• 全量同步时，接口本次没有返回、但 FaceApi 仍存在的人员，删除该人脸记录。
• 增量同步严禁清空整个人脸库，只处理接口返回的人员变化。

四、人脸 SDK 初始化与内存刷新

人脸 SDK 激活、模型初始化、Face DB 初始化仍由启动页负责。人员同步批处理只维护本地业务表和 FaceApi 数据，不在模型未准备好时强行刷新内存库。

启动页在 Face DB 初始化成功后执行 FaceSDKManager.getInstance().initPush()，把本地 FaceApi 数据加载到 SDK 内存库，然后进入主页。

五、离线模式兼容

人员接口失败后继续使用 OfflineStartupPolicy.canOfflineStart() 作为放行条件。允许离线启动时，用户确认后不再请求任何网络同步接口。

人员接口失败
  -> canOfflineStart = true
  -> 用户确认使用本地缓存
  -> 如启用人脸：跳过在线激活，初始化本地模型和 Face DB
  -> initPush()
  -> goMain()

六、需要验证的场景

• 首次初始化：type=1，业务人员和人脸库均可落地，启动后可进入主页。
• 后续启动：type=0，增量新增、编辑、删除都只处理返回人员，不清库。
• 人员接口失败且满足离线条件：用户确认后加载本地人员和本地人脸库进入主页。
• 人员接口失败且不满足离线条件：保留重试/退出流程。
• 定时同步：人员增量同步后不再额外请求 updateFaceData，而是使用人员接口返回数据维护本地人员和人脸库。