feat:人脸机器实时增量更新

lib/common/utils/sync/sync_check_tool.dart

@@ -52,6 +52,9 @@ class SyncCheckTool {
   /// 是否已经完成本轮启动，防止 AppControl 重复注册相同 Cron 任务。
   bool _started = false;
 
+  /// 当前进程最近一次补排部门人脸同步的本地日期，保证同一天最多自动补排一次。
+  DateTime? _lastDepartmentFaceCatchUpDate;
+
   /// 常用规则均使用 cron 0.6.2 可解析的标准字段、范围和步长，不包含 Quartz 专属的 L/W/#。
   static const List<ScheduledCronPreset> cronPresets = [
     ScheduledCronPreset(
@@ -134,6 +137,10 @@ class SyncCheckTool {
         group: ScheduledCronPresetGroup.daily,
         label: '每天 00:30',
         expression: '0 30 0 * * *'),
+    ScheduledCronPreset(
+        group: ScheduledCronPresetGroup.daily,
+        label: '每天 00:40',
+        expression: '0 40 0 * * *'),
     ScheduledCronPreset(
         group: ScheduledCronPresetGroup.daily,
         label: '每天 01:00',
@@ -282,6 +289,12 @@ class SyncCheckTool {
       cron: '0 5 0 * * *',
       idleOnly: true,
     ),
+    ScheduledTaskConfig(
+      type: ScheduledTaskType.departmentFaceSync,
+      enabled: true,
+      cron: '0 40 0 * * *',
+      idleOnly: true,
+    ),
     ScheduledTaskConfig(
       type: ScheduledTaskType.classifySync,
       enabled: false,
@@ -324,8 +337,40 @@ class SyncCheckTool {
     for (final config in configs.values) {
       await _rebuildTask(config);
     }
+    queueMissedDepartmentFaceSync();
   }
 
+  /// 在每天 00:40 之后检查当天是否成功完成部门人脸同步，并在首次启动或恢复时补排一次。
+  ///
+  /// 补排只加入同一人脸任务队列并要求完整空闲，不会阻塞启动或打断支付、识别和业务弹框。
+  void queueMissedDepartmentFaceSync() {
+    if (!_started) return;
+    final config = configs[ScheduledTaskType.departmentFaceSync];
+    if (config == null || !config.enabled) return;
+    final now = DateTime.now();
+    final scheduledAt = DateTime(now.year, now.month, now.day, 0, 40);
+    if (now.isBefore(scheduledAt)) return;
+    final lastSuccess =
+        records[ScheduledTaskType.departmentFaceSync]?.lastSuccessAt;
+    if (_isSameLocalDate(lastSuccess, now) ||
+        _isSameLocalDate(_lastDepartmentFaceCatchUpDate, now)) {
+      return;
+    }
+    _lastDepartmentFaceCatchUpDate = now;
+    unawaited(trigger(
+      ScheduledTaskType.departmentFaceSync,
+      catchUp: true,
+      triggerType: ScheduledTaskTriggerType.system,
+    ));
+  }
+
+  /// 判断两个可空时间是否属于终端本地时区的同一自然日。
+  static bool _isSameLocalDate(DateTime? left, DateTime right) =>
+      left != null &&
+      left.year == right.year &&
+      left.month == right.month &&
+      left.day == right.day;
+
   /// 完成旧 sysJson 一次性迁移，再从 SQLite 加载任务配置、最近结果和上传统计。
   Future<void> _loadState() async {
     final legacyConfigs = (await AppSettingTool.getScheduledTaskConfigs())
@@ -488,6 +533,9 @@ class SyncCheckTool {
     ScheduledTaskType type, {
     bool currentLogOnly = false,
     bool scheduled = false,
+    bool catchUp = false,
+    Set<String>? faceUserIds,
+    bool debugAllFaces = false,
     ScheduledTaskTriggerType triggerType = ScheduledTaskTriggerType.manual,
   }) async {
     final config =
@@ -495,8 +543,12 @@ class SyncCheckTool {
     final request = _PendingTaskRequest(
       currentLogOnly: currentLogOnly,
       requireSafeWindow: !scheduled || config.idleOnly,
-      requireFullIdle: scheduled && config.idleOnly,
+      requireFullIdle: (scheduled || catchUp) && config.idleOnly,
       triggerType: scheduled ? ScheduledTaskTriggerType.cron : triggerType,
+      faceUserIds: faceUserIds == null ? null : Set.unmodifiable(faceUserIds),
+      fullFaceSnapshot:
+          type == ScheduledTaskType.departmentFaceSync && faceUserIds == null,
+      debugAllFaces: debugAllFaces,
     );
     if (runningTasks.contains(type)) {
       _enqueue(type, request);
@@ -577,7 +629,7 @@ class SyncCheckTool {
     try {
       final result = await _runAction(
         type,
-        currentLogOnly: request.currentLogOnly,
+        request: request,
       );
       records[type] = ScheduledTaskRecord(
         lastRunAt: startedAt,
@@ -609,9 +661,11 @@ class SyncCheckTool {
       if (error is TerminalLogUploadException) {
         terminalLogSummary.value = error.summary;
       }
-      final message = error is TerminalLogUploadException
-          ? error.summary.label
-          : error.toString();
+      final message = switch (error) {
+        TerminalLogUploadException() => error.summary.label,
+        FaceSyncPartialFailureException() => error.summary.message,
+        _ => error.toString(),
+      };
       records[type] = ScheduledTaskRecord(
         lastRunAt: startedAt,
         lastSuccessAt: records[type]?.lastSuccessAt,
@@ -632,18 +686,26 @@ class SyncCheckTool {
             nextErrorType: error.runtimeType.toString(),
             nextErrorMessage: _safeError(error),
             nextErrorStack: _safeStack(stack),
-            scanned: error is TerminalLogUploadException
-                ? error.summary.scanned
-                : null,
-            skipped: error is TerminalLogUploadException
-                ? error.summary.skipped
-                : null,
-            succeeded: error is TerminalLogUploadException
-                ? error.summary.succeeded
-                : null,
-            failed: error is TerminalLogUploadException
-                ? error.summary.failed
-                : null,
+            scanned: switch (error) {
+              TerminalLogUploadException() => error.summary.scanned,
+              FaceSyncPartialFailureException() => error.summary.scanned,
+              _ => null,
+            },
+            skipped: switch (error) {
+              TerminalLogUploadException() => error.summary.skipped,
+              FaceSyncPartialFailureException() => error.summary.skipped,
+              _ => null,
+            },
+            succeeded: switch (error) {
+              TerminalLogUploadException() => error.summary.succeeded,
+              FaceSyncPartialFailureException() => error.summary.changed,
+              _ => null,
+            },
+            failed: switch (error) {
+              TerminalLogUploadException() => error.summary.failed,
+              FaceSyncPartialFailureException() => error.summary.failed,
+              _ => null,
+            },
           ),
         );
       }
@@ -698,7 +760,7 @@ class SyncCheckTool {
   /// 将稳定任务类型分派到既有 MQTT、HTTP、插件或文件业务入口并返回统一结果。
   Future<_ScheduledTaskActionResult> _runAction(
     ScheduledTaskType type, {
-    required bool currentLogOnly,
+    required _PendingTaskRequest request,
   }) async {
     switch (type) {
       case ScheduledTaskType.mqReconnect:
@@ -742,6 +804,33 @@ class SyncCheckTool {
       case ScheduledTaskType.configSync:
         await SyncConfigTool.autoSyncSysInfo();
         return const _ScheduledTaskActionResult.success('设备配置同步完成');
+      case ScheduledTaskType.departmentFaceSync:
+        final mode = request.debugAllFaces
+            ? FaceSyncMode.debugAllSnapshot
+            : request.faceUserIds == null
+                ? FaceSyncMode.departmentSnapshot
+                : FaceSyncMode.userDelta;
+        final summary = await SyncFaceTool.sync(
+          mode: mode,
+          userIds: request.faceUserIds,
+        );
+        if (summary.changed > 0 &&
+            request.triggerType == ScheduledTaskTriggerType.mqtt &&
+            Get.isRegistered<AppControl>()) {
+          Get.find<AppControl>().mqUpdateEventBus.fire(MqtActionEnum.FACE);
+        }
+        if (summary.hasFailures) {
+          throw FaceSyncPartialFailureException(summary);
+        }
+        return _ScheduledTaskActionResult.success(
+          summary.message,
+          summary: TerminalLogUploadSummary(
+            scanned: summary.scanned,
+            skipped: summary.skipped,
+            succeeded: summary.changed,
+            failed: summary.failed,
+          ),
+        );
       case ScheduledTaskType.classifySync:
         await SyncProductTool.syncClassify();
         return const _ScheduledTaskActionResult.success('分类同步完成');
@@ -753,7 +842,7 @@ class SyncCheckTool {
         return const _ScheduledTaskActionResult.success('离线订单同步完成');
       case ScheduledTaskType.terminalLogUpload:
         final summary = await TerminalLogUploadTool.upload(
-          currentOnly: currentLogOnly,
+          currentOnly: request.currentLogOnly,
         );
         terminalLogSummary.value = summary;
         return _ScheduledTaskActionResult.success(
@@ -775,6 +864,7 @@ class SyncCheckTool {
   bool _isHeavy(ScheduledTaskType type) {
     return const {
       ScheduledTaskType.configSync,
+      ScheduledTaskType.departmentFaceSync,
       ScheduledTaskType.classifySync,
       ScheduledTaskType.productSync,
       ScheduledTaskType.offlineOrderSync,
@@ -855,6 +945,11 @@ class SyncCheckTool {
             sourceType: ScheduledTaskSourceType.http,
             sourceName: 'HTTP 配置接口',
           ),
+        ScheduledTaskType.departmentFaceSync => const _ScheduledTaskDescriptor(
+            title: '本部门人脸同步',
+            sourceType: ScheduledTaskSourceType.http,
+            sourceName: 'HTTP 人脸快照与虹软插件',
+          ),
         ScheduledTaskType.classifySync => const _ScheduledTaskDescriptor(
             title: '分类同步',
             sourceType: ScheduledTaskSourceType.http,
@@ -932,6 +1027,9 @@ class _PendingTaskRequest {
     required this.requireSafeWindow,
     required this.requireFullIdle,
     required this.triggerType,
+    required this.faceUserIds,
+    required this.fullFaceSnapshot,
+    required this.debugAllFaces,
   });
 
   /// 是否只上传 Logger 当前写入的日志文件；为假时扫描全部日志。
@@ -946,15 +1044,37 @@ class _PendingTaskRequest {
   /// 最终写入任务执行日志的触发来源。
   final ScheduledTaskTriggerType triggerType;
 
+  /// FACE 用户增量回查集合；部门完整快照时为空。
+  final Set<String>? faceUserIds;
+
+  /// 当前请求是否为部门或调试完整快照，用于合并时让全量覆盖用户增量。
+  final bool fullFaceSnapshot;
+
+  /// 是否执行仅非生产可触发的全租户调试快照。
+  final bool debugAllFaces;
+
   /// 全量日志请求优先于“仅当前文件”；任一手动请求到达后只需等待安全窗口。
-  _PendingTaskRequest merge(_PendingTaskRequest other) => _PendingTaskRequest(
-        currentLogOnly: currentLogOnly && other.currentLogOnly,
-        requireSafeWindow: requireSafeWindow || other.requireSafeWindow,
-        requireFullIdle: requireFullIdle && other.requireFullIdle,
-        triggerType: triggerType == ScheduledTaskTriggerType.cron
-            ? other.triggerType
-            : triggerType,
-      );
+  _PendingTaskRequest merge(_PendingTaskRequest other) {
+    final mergedFullFaceSnapshot = fullFaceSnapshot || other.fullFaceSnapshot;
+    final mergedUserIds = mergedFullFaceSnapshot
+        ? null
+        : <String>{...?faceUserIds, ...?other.faceUserIds};
+    return _PendingTaskRequest(
+      currentLogOnly: currentLogOnly && other.currentLogOnly,
+      requireSafeWindow: requireSafeWindow || other.requireSafeWindow,
+      // Cron/补排全量一旦进入队列，不因随后到达的 MQ 增量而降低 60 秒空闲要求。
+      requireFullIdle: mergedFullFaceSnapshot
+          ? requireFullIdle || other.requireFullIdle
+          : requireFullIdle && other.requireFullIdle,
+      triggerType: triggerType == ScheduledTaskTriggerType.cron
+          ? other.triggerType
+          : triggerType,
+      faceUserIds:
+          mergedUserIds == null ? null : Set.unmodifiable(mergedUserIds),
+      fullFaceSnapshot: mergedFullFaceSnapshot,
+      debugAllFaces: debugAllFaces || other.debugAllFaces,
+    );
+  }
 }
 
 /// MQTT 等外部依赖暂不可用时使用的可诊断任务异常。

lib/common/utils/sync/sync_face_tool.dart

@@ -1,266 +1,602 @@
 import 'dart:io';
 
-import 'package:common_utils/common_utils.dart';
 import 'package:flutter/material.dart';
 import 'package:get/get.dart';
 
 import 'package:pj_supermarket_cloud/common/index.dart';
 
-class SyncFaceTool {
-  static const _tag = "sync人脸工具";
+/// 应用级人脸差异同步服务，供页面、Cron、MQ 和识别异常恢复共同复用。
+abstract class SyncFaceTool {
+  /// 人脸同步日志标签；日志只记录汇总和脱敏样本，不记录姓名、图片地址或特征。
+  static const String _tag = '人脸差异同步';
 
-  // 删除数据库中为空的人脸
+  /// V3 游标快照页面大小。
+  static const int _snapshotPageSize = 200;
+
+  /// V2 调试全租户同步页面大小，仅非生产入口使用。
+  static const int _debugPageSize = 100;
+
+  /// 单次日志最多保留的脱敏失败样本数量，避免异常数据导致日志膨胀。
+  static const int _maxFailureSamples = 20;
+
+  /// V3 游标保护页数，避免异常服务端持续返回 hasMore 造成无限循环。
+  static const int _maxSnapshotPages = 10000;
+
+  /// 删除数据库中缺少本地特征或图片的历史残缺人脸。
+  ///
+  /// 删除顺序仍先处理虹软内存库；单条失败时保留记录供后续权威快照重试。
   static Future<void> delEmptyFace() async {
-    final app = Get.find<AppControl>();
-    final faceDao = app.dataBase.getFaceDao;
-    final faceList = await faceDao.getEmptyFaceList();
-    if (ObjectUtil.isEmptyList(faceList)) return;
-    for (final v in faceList!) {
-      if (ObjectUtil.isNotEmpty(v.path)) {
-        await delFaceByStorage(filePath: v.path!);
-      }
-      await faceDao.delById(v.id!);
+    final faceDao = Get.find<AppControl>().dataBase.getFaceDao;
+    final faces = await faceDao.getEmptyFaceList() ?? const [];
+    for (final face in faces) {
+      await _deleteLocalFace(face, faceDao);
     }
   }
 
-  // 同步人脸
-  static Future<void> syncFace({
+  /// 兼容既有页面与识别恢复调用的统一入口。
+  ///
+  /// [isAll] 只允许非生产调试使用；生产调用即使误传也会收敛为本部门快照。
+  static Future<FaceSyncSummary> syncFace({
     bool isAll = false,
     VoidCallback? onSyncGroup,
   }) async {
-    final appSetting = await AppSettingTool.getSysSetting();
-    final merchantDeptId = appSetting.merchantDeptId;
-    // 人脸存储路径
+    final mode = isAll && !AppSysTool.isProd()
+        ? FaceSyncMode.debugAllSnapshot
+        : FaceSyncMode.departmentSnapshot;
+    final summary = await sync(mode: mode);
+    onSyncGroup?.call();
+    return summary;
+  }
+
+  /// 执行部门权威快照或一组用户增量；用户集合按稳定顺序串行处理。
+  ///
+  /// 完整快照会一次性拉入内存并完成唯一性、游标和页面连续性校验，
+  /// 任何页面中断都会抛出异常且不会进入本地孤儿删除阶段。
+  static Future<FaceSyncSummary> sync({
+    required FaceSyncMode mode,
+    Set<String>? userIds,
+  }) async {
+    if (!AppNetworkTool.isAutoNetwork()) {
+      throw const FaceSyncSnapshotException('网络不可用，无法获取人脸权威快照');
+    }
+    final setting = await AppSettingTool.getSysSetting();
+    final merchantDeptId = setting.merchantDeptId?.trim();
+    if (merchantDeptId == null || merchantDeptId.isEmpty) {
+      throw const FaceSyncSnapshotException('终端尚未绑定商户部门');
+    }
     final storagePath = await AppFileTool.getFacePath();
-    if (ObjectUtil.isEmpty(storagePath)) {
-      logger.e("|$_tag|同步人脸错误,创建人脸存储路径错误");
+    if (storagePath == null || storagePath.isEmpty) {
+      throw const FaceSyncSnapshotException('无法创建人脸本地存储目录');
+    }
+    if (!AppRuntimeTool.useManualHardwareInput &&
+        AppSysTool.isProd() &&
+        !await AppFaceTool.isActiveSdk()) {
+      throw const FaceSyncSnapshotException('人脸 SDK 未激活，无法安全更新人脸库');
+    }
+
+    final accumulator = _FaceSyncAccumulator(mode);
+    if (mode == FaceSyncMode.userDelta) {
+      final normalizedUserIds = (userIds ?? const <String>{})
+          .map((item) => item.trim())
+          .where((item) => item.isNotEmpty)
+          .toSet()
+          .toList()
+        ..sort();
+      if (normalizedUserIds.isEmpty) {
+        throw const FaceSyncSnapshotException('用户增量同步缺少用户标识');
+      }
+      for (final userId in normalizedUserIds) {
+        final remote = await _loadV3Snapshot(
+          merchantDeptId: merchantDeptId,
+          userId: userId,
+        );
+        if (remote.length > 3) {
+          throw FaceSyncSnapshotException(
+            '用户 ${_maskSampleId(userId)} 的服务端人脸超过3张，已停止本次增量',
+          );
+        }
+        final local =
+            await Get.find<AppControl>().dataBase.getFaceDao.findByUserId(
+                      userId,
+                    ) ??
+                const [];
+        await _reconcile(
+          remote: remote,
+          local: local,
+          storagePath: storagePath,
+          accumulator: accumulator,
+        );
+      }
+    } else {
+      final remote = mode == FaceSyncMode.debugAllSnapshot
+          ? await _loadDebugAllSnapshot()
+          : await _loadV3Snapshot(merchantDeptId: merchantDeptId);
+      final local = await Get.find<AppControl>().dataBase.getFaceDao.getAll();
+      await _reconcile(
+        remote: remote,
+        local: local,
+        storagePath: storagePath,
+        accumulator: accumulator,
+      );
+    }
+    final summary = accumulator.toSummary();
+    logger.i('|$_tag|同步完成|${summary.message}|');
+    return summary;
+  }
+
+  /// 拉取 V3 固定上界游标快照并校验页面连续性、记录唯一性和字段有效性。
+  static Future<List<ServiceFaceSyncRecord>> _loadV3Snapshot({
+    required String merchantDeptId,
+    String? userId,
+  }) async {
+    var afterId = '0';
+    String? snapshotMaxId;
+    final records = <ServiceFaceSyncRecord>[];
+    final databaseIds = <String>{};
+    final sampleIds = <String>{};
+    for (var page = 0; page < _maxSnapshotPages; page++) {
+      final snapshot = await UserApi.getFaceSyncSnapshot({
+        'merchantDeptId': merchantDeptId,
+        'userId': userId,
+        'afterId': afterId,
+        'limit': _snapshotPageSize,
+        'snapshotMaxId': snapshotMaxId,
+      });
+      snapshotMaxId ??= snapshot.snapshotMaxId;
+      if (snapshot.snapshotMaxId != snapshotMaxId) {
+        throw const FaceSyncSnapshotException('人脸快照上界在分页期间发生变化');
+      }
+      var previousId = int.tryParse(afterId) ?? 0;
+      for (final record in snapshot.records) {
+        final currentId = int.tryParse(record.id);
+        final sampleId = int.tryParse(record.sampleId);
+        if (currentId == null || currentId <= previousId) {
+          throw const FaceSyncSnapshotException('人脸快照游标不连续或发生倒退');
+        }
+        if (sampleId == null || sampleId <= 0 || sampleId > 2147483647) {
+          throw FaceSyncSnapshotException(
+            '存在无效人脸编号 ${_maskSampleId(record.sampleId)}',
+          );
+        }
+        if (!databaseIds.add(record.id) || !sampleIds.add(record.sampleId)) {
+          throw FaceSyncSnapshotException(
+            '人脸快照包含重复编号 ${_maskSampleId(record.sampleId)}',
+          );
+        }
+        if (userId != null && record.userId != userId) {
+          throw const FaceSyncSnapshotException('用户增量快照返回了其他用户数据');
+        }
+        if (record.faceImg == null || record.faceImg!.trim().isEmpty) {
+          throw FaceSyncSnapshotException(
+            '人脸 ${_maskSampleId(record.sampleId)} 缺少图片地址',
+          );
+        }
+        records.add(record);
+        previousId = currentId;
+      }
+      final expectedNext =
+          snapshot.records.isEmpty ? afterId : snapshot.records.last.id;
+      if (snapshot.nextAfterId != expectedNext) {
+        throw const FaceSyncSnapshotException('人脸快照下一页游标与当前页不一致');
+      }
+      if (!snapshot.hasMore) return records;
+      if (snapshot.records.isEmpty) {
+        throw const FaceSyncSnapshotException('人脸快照存在空页但仍声明后续数据');
+      }
+      afterId = snapshot.nextAfterId;
+    }
+    throw const FaceSyncSnapshotException('人脸快照分页超过安全上限');
+  }
+
+  /// 使用保留的 V2 接口拉取非生产调试全租户快照。
+  ///
+  /// 生产入口不会调用本方法；V2 不提供源更新时间，因此仅以图片地址判断图片版本。
+  static Future<List<ServiceFaceSyncRecord>> _loadDebugAllSnapshot() async {
+    final records = <ServiceFaceSyncRecord>[];
+    final sampleIds = <String>{};
+    for (var page = 1; page <= _maxSnapshotPages; page++) {
+      final data = await UserApi.getFaceListV2({
+        'current': page,
+        'size': _debugPageSize,
+        'merchantDeptId': '',
+      });
+      if (data == null) {
+        throw const FaceSyncSnapshotException('调试全租户人脸接口未返回有效数据');
+      }
+      for (final face in data) {
+        final sampleId = face.autoCode?.trim();
+        final userId = face.userId?.trim();
+        if (sampleId == null ||
+            userId == null ||
+            sampleId.isEmpty ||
+            userId.isEmpty ||
+            !sampleIds.add(sampleId)) {
+          throw const FaceSyncSnapshotException('调试全租户快照包含无效或重复人脸编号');
+        }
+        records.add(ServiceFaceSyncRecord(
+          id: face.id ?? sampleId,
+          sampleId: sampleId,
+          userId: userId,
+          username: face.username,
+          deptId: face.deptId ?? '',
+          deptName: face.deptName,
+          faceImg: face.faceImg,
+        ));
+      }
+      if (data.length < _debugPageSize) return records;
+    }
+    throw const FaceSyncSnapshotException('调试全租户快照分页超过安全上限');
+  }
+
+  /// 对完整服务端集合与指定范围本地集合做差异，只处理新增、变化和孤儿记录。
+  static Future<void> _reconcile({
+    required List<ServiceFaceSyncRecord> remote,
+    required List<FaceEntity> local,
+    required String storagePath,
+    required _FaceSyncAccumulator accumulator,
+  }) async {
+    final faceDao = Get.find<AppControl>().dataBase.getFaceDao;
+    final localBySampleId = <String, FaceEntity>{};
+    for (final face in local) {
+      if (localBySampleId.containsKey(face.sampleId)) {
+        throw FaceSyncSnapshotException(
+          '本地存在重复人脸编号 ${_maskSampleId(face.sampleId)}',
+        );
+      }
+      localBySampleId[face.sampleId] = face;
+    }
+
+    for (final record in remote) {
+      accumulator.scanned++;
+      final existing = localBySampleId.remove(record.sampleId);
+      final imageChanged = await _imageChanged(existing, record);
+      if (existing == null || imageChanged) {
+        final success = await _upsertImageFace(
+          record: record,
+          existing: existing,
+          storagePath: storagePath,
+          faceDao: faceDao,
+        );
+        if (success) {
+          existing == null ? accumulator.added++ : accumulator.updated++;
+        } else {
+          accumulator.fail(record.sampleId);
+        }
+        continue;
+      }
+      if (_metadataChanged(existing, record)) {
+        await faceDao.edit(_toEntity(record, existing: existing));
+        accumulator.updated++;
+      } else {
+        accumulator.skipped++;
+      }
+    }
+
+    // 只有远端完整集合已经成功拉取和校验后才会执行此处的集合差删除。
+    for (final orphan in localBySampleId.values) {
+      if (await _deleteLocalFace(orphan, faceDao)) {
+        accumulator.deleted++;
+      } else {
+        accumulator.fail(orphan.sampleId);
+      }
+    }
+  }
+
+  /// 判断图片版本、特征或正式文件是否变化；完全一致时不下载也不写虹软。
+  static Future<bool> _imageChanged(
+    FaceEntity? existing,
+    ServiceFaceSyncRecord record,
+  ) async {
+    if (existing == null) return true;
+    if (existing.imagePath != record.faceImg) return true;
+    if (record.sourceUpdatedAt != null &&
+        existing.updateTime != record.sourceUpdatedAt) {
+      return true;
+    }
+    if ((existing.faceModel ?? const []).isEmpty) return true;
+    final path = existing.path;
+    return path == null || path.isEmpty || !await File(path).exists();
+  }
+
+  /// 判断姓名或部门元数据是否变化；此类变化不需要重新提取图片特征。
+  static bool _metadataChanged(
+    FaceEntity existing,
+    ServiceFaceSyncRecord record,
+  ) =>
+      existing.userId != record.userId ||
+      existing.userName != (record.username ?? '') ||
+      existing.deptId != record.deptId ||
+      existing.deptName != (record.deptName ?? '');
+
+  /// 下载临时图片、提取特征并提交文件、SQLite 和虹软单样本增量。
+  ///
+  /// 虹软替换失败时原生保留旧特征，本方法随后回滚 SQLite 和新文件；新样本失败则不留正式记录。
+  static Future<bool> _upsertImageFace({
+    required ServiceFaceSyncRecord record,
+    required FaceEntity? existing,
+    required String storagePath,
+    required FaceDao faceDao,
+  }) async {
+    File? temporaryFile;
+    File? finalFile;
+    var databaseChanged = false;
+    try {
+      temporaryFile = await _downloadTemporaryFace(record, storagePath);
+      final featureData = AppRuntimeTool.useManualHardwareInput
+          ? <int>[]
+          : (await FaceDiscernPlugs.extractFaceFeature(
+              filePath: temporaryFile.path,
+            ))
+              .featureData;
+      if (!AppRuntimeTool.useManualHardwareInput && featureData.isEmpty) {
+        throw const FaceSyncSnapshotException('图片未提取到可注册人脸');
+      }
+
+      finalFile = File(_officialFilePath(record, storagePath));
+      if (await finalFile.exists()) await finalFile.delete();
+      await temporaryFile.rename(finalFile.path);
+      temporaryFile = null;
+      final entity = _toEntity(
+        record,
+        existing: existing,
+        path: finalFile.path,
+        faceModel: featureData,
+      );
+      if (existing == null) {
+        final id = await faceDao.save(entity);
+        if (id == null) throw const FaceSyncSnapshotException('本地人脸记录写入失败');
+        entity.id = id;
+      } else {
+        await faceDao.edit(entity);
+      }
+      databaseChanged = true;
+
+      if (!AppRuntimeTool.useManualHardwareInput) {
+        final applied = await FaceDiscernPlugs.applyFaceDelta(
+          operation: 'upsert',
+          sampleId: record.sampleId,
+          userId: record.userId,
+          username: record.username ?? '',
+          featureData: featureData,
+        );
+        if (!applied.success) throw FaceSyncSnapshotException(applied.message);
+      }
+      if (existing?.path != null && existing!.path != finalFile.path) {
+        await delFaceByStorage(filePath: existing.path!);
+      }
+      return true;
+    } catch (error, stack) {
+      logger.w(
+        '|$_tag|样本处理失败sampleId:${_maskSampleId(record.sampleId)}|error:${error.runtimeType}|stack:$stack|',
+      );
+      if (databaseChanged) {
+        try {
+          if (existing == null) {
+            await faceDao.delBySampleId(record.sampleId);
+          } else {
+            await faceDao.edit(existing);
+          }
+        } catch (rollbackError, rollbackStack) {
+          logger.e(
+            '|$_tag|回滚本地人脸失败sampleId:${_maskSampleId(record.sampleId)}|error:$rollbackError|stack:$rollbackStack|',
+          );
+        }
+      }
+      if (finalFile != null) await delFaceByStorage(filePath: finalFile.path);
+      return false;
+    } finally {
+      if (temporaryFile != null) {
+        await delFaceByStorage(filePath: temporaryFile.path);
+      }
+    }
+  }
+
+  /// 删除本地孤儿人脸；虹软失败或 SQLite 失败时恢复文件和旧特征。
+  static Future<bool> _deleteLocalFace(
+    FaceEntity face,
+    FaceDao faceDao,
+  ) async {
+    File? originalFile;
+    File? pendingFile;
+    try {
+      if (face.path != null && face.path!.isNotEmpty) {
+        originalFile = File(face.path!);
+        if (await originalFile.exists()) {
+          pendingFile = File('${face.path}.pending-delete');
+          if (await pendingFile.exists()) await pendingFile.delete();
+          await originalFile.rename(pendingFile.path);
+        }
+      }
+      if (!AppRuntimeTool.useManualHardwareInput) {
+        final removed = await FaceDiscernPlugs.applyFaceDelta(
+          operation: 'delete',
+          sampleId: face.sampleId,
+        );
+        if (!removed.success) throw FaceSyncSnapshotException(removed.message);
+      }
+      await faceDao.delBySampleId(face.sampleId);
+      if (pendingFile != null) {
+        await delFaceByStorage(filePath: pendingFile.path);
+      }
+      return true;
+    } catch (error, stack) {
+      logger.w(
+        '|$_tag|删除样本失败sampleId:${_maskSampleId(face.sampleId)}|error:${error.runtimeType}|stack:$stack|',
+      );
+      try {
+        if (pendingFile != null && await pendingFile.exists()) {
+          await pendingFile.rename(originalFile!.path);
+        }
+        final stillExists = await faceDao.findBySampleId(face.sampleId);
+        if (stillExists == null) await faceDao.save(face);
+        await _restoreNativeFace(face);
+      } catch (rollbackError, rollbackStack) {
+        logger.e(
+          '|$_tag|回滚删除失败sampleId:${_maskSampleId(face.sampleId)}|error:$rollbackError|stack:$rollbackStack|',
+        );
+      }
+      return false;
+    }
+  }
+
+  /// 删除回滚时恢复旧内存特征；历史记录无特征时按用户从仍存在的 SQLite 重新装载。
+  static Future<void> _restoreNativeFace(FaceEntity face) async {
+    if (AppRuntimeTool.useManualHardwareInput) return;
+    final featureData = (face.faceModel ?? const [])
+        .map((item) => (item as num).toInt())
+        .toList();
+    if (featureData.isNotEmpty) {
+      await FaceDiscernPlugs.applyFaceDelta(
+        operation: 'upsert',
+        sampleId: face.sampleId,
+        userId: face.userId,
+        username: face.userName,
+        featureData: featureData,
+      );
       return;
     }
-    // 同步没有的人脸
-    int pageNo = 1;
-    bool isNext = true;
-    while (isNext) {
-      final bool = await syncGroupFace(
-        pageNo: pageNo,
-        merchantDeptId: isAll ? "" : merchantDeptId!,
-        storagePath: storagePath!,
+    await FaceDiscernPlugs.rebuildFaceLibrary(userId: face.userId);
+  }
+
+  /// 下载远端图片到专用临时目录；下载失败不会覆盖任何正式文件。
+  static Future<File> _downloadTemporaryFace(
+    ServiceFaceSyncRecord record,
+    String storagePath,
+  ) async {
+    final imageUrl = record.faceImg!;
+    final bytes = await AppNetworkTool.downloadImage(imageUrl);
+    if (bytes == null || bytes.isEmpty) {
+      throw const FaceSyncSnapshotException('人脸图片下载失败');
+    }
+    final directory = Directory('$storagePath/.face-sync-temp');
+    if (!await directory.exists()) await directory.create(recursive: true);
+    final file = File(
+      '${directory.path}/${record.sampleId}_${DateTime.now().microsecondsSinceEpoch}.tmp',
+    );
+    await file.writeAsBytes(bytes, flush: true);
+    return file;
+  }
+
+  /// 生成人脸正式文件路径；版本戳确保新文件写入前旧文件始终可回滚。
+  static String _officialFilePath(
+    ServiceFaceSyncRecord record,
+    String storagePath,
+  ) {
+    final extension = AppFileTool.getFileExtension(record.faceImg!);
+    final sourceVersion = record.sourceUpdatedAt?.millisecondsSinceEpoch ?? 0;
+    final writeVersion = DateTime.now().microsecondsSinceEpoch;
+    return '$storagePath/${record.userId}_${record.sampleId}_${sourceVersion}_$writeVersion$extension';
+  }
+
+  /// 将服务端快照合并为 Floor 现有 FaceEntity，不改变 SQLite 字段结构。
+  static FaceEntity _toEntity(
+    ServiceFaceSyncRecord record, {
+    required FaceEntity? existing,
+    String? path,
+    List<int>? faceModel,
+  }) =>
+      FaceEntity(
+        id: existing?.id,
+        userId: record.userId,
+        sampleId: record.sampleId,
+        userName: record.username ?? '',
+        deptId: record.deptId,
+        deptName: record.deptName ?? '',
+        imagePath: record.faceImg ?? '',
+        path: path ?? existing?.path,
+        faceModel: faceModel ?? existing?.faceModel,
+        createTime: existing?.createTime ?? DateTime.now(),
+        updateTime: record.sourceUpdatedAt ?? existing?.updateTime,
       );
-      if (isNext != bool) isNext = bool;
-      if (!bool) break;
-      pageNo += 1;
-      onSyncGroup?.call();
-    }
-  }
 
-  static Future<bool> syncGroupFace({
-    required int pageNo,
-    required String merchantDeptId,
-    required String storagePath,
-    String? userId,
-    bool? isGlobalFace,
-  }) async {
-    final app = Get.find<AppControl>();
-    final faceDao = app.dataBase.getFaceDao;
-    const size = 100;
-    var pa = {
-      "current": pageNo,
-      "size": size,
-      "userId": userId,
-      "merchantDeptId": merchantDeptId,
-    };
-    if (isGlobalFace != null && isGlobalFace) pa["merchantDeptId"] = null;
-    logger.i("|$_tag|同步人脸api参数:|$pa|");
-    try {
-      final data = await UserApi.getFaceListV2(pa);
-      if (data == null) throw Error();
-      if (ObjectUtil.isEmptyList(data)) {
-        if (ObjectUtil.isEmpty(userId)) {
-          // 全量同步第 1 页为空时，服务端没有任何人脸，必须同步清空本地库和原生人脸库。
-          if (pageNo == 1 && ObjectUtil.isEmpty(merchantDeptId)) {
-            await faceDao.delAll();
-            await AppFaceTool.removeFace(sampleId: '-1');
-          }
-          return false;
-        }
-        // 删除人脸图片
-        final faceList = await faceDao.findByUserId(userId!);
-        if (!ObjectUtil.isEmptyList(faceList)) {
-          for (final v in faceList!) {
-            if (ObjectUtil.isNotEmpty(v.path)) {
-              await delFaceByStorage(filePath: v.path!);
-              await AppFaceTool.removeFace(sampleId: v.sampleId);
-            }
-          }
-        }
-        // 删除数据库
-        await faceDao.delByUserId(userId);
-        return false;
-      }
-      if (isGlobalFace != null && !isGlobalFace) return false;
-      if (userId != null) {
-        final dbUserList = await faceDao.findByUserId(userId);
-        if (!ObjectUtil.isEmptyList(dbUserList)) {
-          for (final v in dbUserList!) {
-            final target = data.firstWhereOrNull((i) => i.id == v.sampleId);
-            if (target == null) {
-              if (ObjectUtil.isNotEmpty(v.path)) {
-                await delFaceByStorage(filePath: v.path!);
-                await AppFaceTool.removeFace(sampleId: v.sampleId);
-              }
-              await faceDao.delById(v.id!);
-            }
-          }
-        }
-      }
-      for (final v in data) {
-        if (ObjectUtil.isEmpty(v.autoCode) || ObjectUtil.isEmpty(v.userId)) {
-          logger.e(
-            "|$_tag|同步人脸跳过无效数据:|autoCode=${v.autoCode}|userId=${v.userId}|deptId=${v.deptId}|username=${v.username}|",
-          );
-          continue;
-        }
-
-        final sampleId = v.autoCode!;
-        final userId = v.userId!;
-        // 删除人脸
-        if (v.delFlag == true) {
-          // 先查询数据库是否存在
-          final detail = await faceDao.findBySampleId(sampleId);
-          if (detail == null) {
-            continue;
-          }
-          if (ObjectUtil.isNotEmpty(detail.path)) {
-            await delFaceByStorage(filePath: detail.path!);
-          }
-          await AppFaceTool.removeFace(sampleId: sampleId);
-          await faceDao.delBySampleId(sampleId);
-          continue;
-        }
-        final faceEntity = await faceDao.findBySampleId(sampleId);
-        if (faceEntity == null) {
-          final add = FaceEntity(
-            userId: userId,
-            sampleId: sampleId,
-            userName: v.username ?? "",
-            deptId: v.deptId,
-            deptName: v.deptName ?? "",
-            imagePath: v.faceImg ?? "",
-            createTime: DateTime.now(),
-          );
-          final addId = await faceDao.save(add);
-          if (addId != null) {
-            String? fileName = generateFaceFileName(
-              userId: add.userId,
-              sampleId: add.sampleId,
-              username: add.userName,
-              facePath: add.imagePath,
-            );
-            final filePath = await writeFaceByStorage(
-              storagePath: storagePath,
-              fileName: fileName,
-              facePath: add.imagePath,
-            );
-            if (ObjectUtil.isNotEmpty(filePath)) {
-              add.id = addId;
-              add.updateTime = DateTime.now();
-              add.path = filePath;
-              await faceDao.edit(add);
-            }
-          }
-          await AppFaceTool.removeFace(sampleId: add.sampleId);
-          await AppFaceTool.faceRegister(
-            userId: add.userId.toString(),
-            forceRegister: true,
-          );
-          continue;
-        }
-        final edit = FaceEntity(
-          id: faceEntity.id!,
-          userId: userId,
-          sampleId: sampleId,
-          userName: v.username ?? "",
-          deptId: v.deptId,
-          deptName: v.deptName ?? "",
-          imagePath: v.faceImg ?? "",
-          createTime: DateTime.now(),
-        );
-        if (edit == faceEntity) {
-          continue;
-        }
-        String? fileName = generateFaceFileName(
-          userId: edit.userId,
-          sampleId: edit.sampleId,
-          username: edit.userName,
-          facePath: edit.imagePath,
-        );
-        final filePath = await writeFaceByStorage(
-          storagePath: storagePath,
-          facePath: edit.imagePath,
-          fileName: fileName,
-        );
-        if (ObjectUtil.isNotEmpty(filePath)) {
-          if (ObjectUtil.isNotEmpty(edit.path)) {
-            await delFaceByStorage(filePath: edit.path!);
-          }
-          edit.path = filePath;
-        }
-        await faceDao.edit(edit);
-        // 重新生成人脸模型
-        await AppFaceTool.removeFace(sampleId: edit.sampleId);
-        await AppFaceTool.faceRegister(
-          userId: edit.userId.toString(),
-          forceRegister: true,
-        );
-      }
-      if (data.length >= size) return true;
-    } catch (e, stack) {
-      logger.e("|$_tag|同步人脸意外的错误error:|$e|stack:|$stack|");
-    }
-    return false;
-  }
-
-  /// 删除人脸图片
-  static Future<void> delFaceByStorage({
-    required String filePath,
-  }) async {
+  /// 删除指定本地文件；失败只记录文件路径以外的异常类型，避免同步主流程被清理动作中断。
+  static Future<void> delFaceByStorage({required String filePath}) async {
     try {
       final file = File(filePath);
-      if (await file.exists()) {
-        await file.delete();
-      }
-    } catch (e) {
-      logger.e("|$_tag|删除人脸图片意外的错误error:|$e|");
+      if (await file.exists()) await file.delete();
+    } catch (error, stack) {
+      logger.w('|$_tag|删除人脸文件失败|error:${error.runtimeType}|stack:$stack|');
     }
   }
 
+  /// 为兼容其他历史调用保留的文件名生成方法；新差异同步使用带版本戳的内部路径。
   static String? generateFaceFileName({
     required String userId,
     required String sampleId,
     required String username,
     required String facePath,
   }) {
-    if (ObjectUtil.isEmpty(facePath)) return null;
-    return "${userId}_${sampleId}_$username${AppFileTool.getFileExtension(facePath)}";
+    if (facePath.isEmpty) return null;
+    return '${userId}_${sampleId}_$username${AppFileTool.getFileExtension(facePath)}';
   }
 
-  /// 写入人脸头像到本地磁盘
+  /// 为兼容其他历史调用保留的下载方法；新差异同步使用临时文件校验后再提升为正式文件。
   static Future<String?> writeFaceByStorage({
     required String storagePath,
     required String? fileName,
     required String facePath,
   }) async {
-    if (ObjectUtil.isEmpty(fileName)) return null;
-    final storageDirectory = Directory(storagePath);
-    final file = File('${storageDirectory.path}/$fileName');
-    if (await file.exists()) {
-      await file.delete();
-    }
-    final bytesImg = await AppNetworkTool.downloadImage(facePath);
-    if (bytesImg == null) return null;
-    final writeFile = await file.writeAsBytes(bytesImg);
-    if (await writeFile.exists()) {
-      return file.path;
-    }
-    return null;
+    if (fileName == null || fileName.isEmpty) return null;
+    final bytes = await AppNetworkTool.downloadImage(facePath);
+    if (bytes == null || bytes.isEmpty) return null;
+    final file = File('$storagePath/$fileName');
+    await file.writeAsBytes(bytes, flush: true);
+    return await file.exists() ? file.path : null;
+  }
+
+  /// 对虹软搜索标识进行脱敏，日志不输出完整样本编号。
+  static String _maskSampleId(String value) {
+    if (value.length <= 4) return '***$value';
+    return '${value.substring(0, 1)}***${value.substring(value.length - 3)}';
   }
 }
+
+/// 人脸同步内部可变统计器，单次任务结束后转换为不可变汇总。
+class _FaceSyncAccumulator {
+  /// 创建指定同步模式的空统计器。
+  _FaceSyncAccumulator(this.mode);
+
+  /// 本次同步业务模式。
+  final FaceSyncMode mode;
+
+  /// 已扫描服务端记录数。
+  int scanned = 0;
+
+  /// 成功新增样本数。
+  int added = 0;
+
+  /// 成功更新样本数。
+  int updated = 0;
+
+  /// 成功删除孤儿样本数。
+  int deleted = 0;
+
+  /// 无变化跳过样本数。
+  int skipped = 0;
+
+  /// 处理失败样本数。
+  int failed = 0;
+
+  /// 有限保存的脱敏失败样本。
+  final List<String> maskedFailedSampleIds = [];
+
+  /// 累加一个失败样本并按上限保存脱敏编号。
+  void fail(String sampleId) {
+    failed++;
+    if (maskedFailedSampleIds.length < SyncFaceTool._maxFailureSamples) {
+      maskedFailedSampleIds.add(SyncFaceTool._maskSampleId(sampleId));
+    }
+  }
+
+  /// 生成可公开给任务日志和页面的不可变汇总。
+  FaceSyncSummary toSummary() => FaceSyncSummary(
+        mode: mode,
+        scanned: scanned,
+        added: added,
+        updated: updated,
+        deleted: deleted,
+        skipped: skipped,
+        failed: failed,
+        maskedFailedSampleIds: List.unmodifiable(maskedFailedSampleIds),
+      );
+}