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

lib/common/models/api/user_api_models.dart

@@ -136,6 +136,108 @@ class ServiceAsyncFace {
   Map<String, dynamic> toJson() => _$ServiceAsyncFaceToJson(this);
 }
 
+/// V3 部门人脸快照中的单条服务端权威记录。
+@JsonSerializable()
+class ServiceFaceSyncRecord {
+  /// 人脸记录数据库主键，作为分页顺序和快照范围的稳定标识。
+  @JsonKey(
+    fromJson: JsonTool.anyToRequiredString,
+    toJson: JsonTool.stringToInt,
+  )
+  final String id;
+
+  /// 虹软 32 位搜索标识，来源于服务端 autoCode。
+  @JsonKey(
+    fromJson: JsonTool.anyToRequiredString,
+    toJson: JsonTool.stringToInt,
+  )
+  final String sampleId;
+
+  /// 人脸所属用户主键，MQ 增量按该字段回查同一用户的全部人脸。
+  @JsonKey(
+    fromJson: JsonTool.anyToRequiredString,
+    toJson: JsonTool.stringToInt,
+  )
+  final String userId;
+
+  /// 用户姓名，用于本地识别结果和设置页展示。
+  final String? username;
+
+  /// 用户当前部门主键，保证终端只维护绑定部门及其子部门人脸。
+  @JsonKey(
+    fromJson: JsonTool.anyToRequiredString,
+    toJson: JsonTool.stringToInt,
+  )
+  final String deptId;
+
+  /// 用户当前部门名称，用于本地展示。
+  final String? deptName;
+
+  /// 服务端人脸图片地址，地址变化会触发重新下载与特征提取。
+  final String? faceImg;
+
+  /// 服务端人脸记录修改时间，和图片地址共同构成图片版本。
+  final DateTime? sourceUpdatedAt;
+
+  /// 创建一条 V3 人脸快照记录。
+  const ServiceFaceSyncRecord({
+    required this.id,
+    required this.sampleId,
+    required this.userId,
+    this.username,
+    required this.deptId,
+    this.deptName,
+    this.faceImg,
+    this.sourceUpdatedAt,
+  });
+
+  /// 从统一网络层返回的 JSON 创建快照记录。
+  factory ServiceFaceSyncRecord.fromJson(Map<String, dynamic> json) =>
+      _$ServiceFaceSyncRecordFromJson(json);
+
+  /// 将快照记录转换为 JSON，主要供模型测试和诊断使用。
+  Map<String, dynamic> toJson() => _$ServiceFaceSyncRecordToJson(this);
+}
+
+/// V3 部门人脸同步的固定上界游标页面。
+@JsonSerializable()
+class ServiceFaceSyncSnapshot {
+  /// 当前页面记录，服务端保证按数据库主键严格升序返回。
+  final List<ServiceFaceSyncRecord> records;
+
+  /// 下一页排他游标；末页仅用于终端完成连续性校验。
+  @JsonKey(
+    fromJson: JsonTool.anyToRequiredString,
+    toJson: JsonTool.stringToInt,
+  )
+  final String nextAfterId;
+
+  /// 是否还有位于固定快照上界内的下一页。
+  final bool hasMore;
+
+  /// 首次请求固定的人脸数据库主键上界，后续请求必须原样携带。
+  @JsonKey(
+    fromJson: JsonTool.anyToRequiredString,
+    toJson: JsonTool.stringToInt,
+  )
+  final String snapshotMaxId;
+
+  /// 创建一个固定上界游标页面。
+  const ServiceFaceSyncSnapshot({
+    required this.records,
+    required this.nextAfterId,
+    required this.hasMore,
+    required this.snapshotMaxId,
+  });
+
+  /// 从统一网络层返回的 JSON 创建快照页面。
+  factory ServiceFaceSyncSnapshot.fromJson(Map<String, dynamic> json) =>
+      _$ServiceFaceSyncSnapshotFromJson(json);
+
+  /// 将快照页面转换为 JSON，主要供模型测试使用。
+  Map<String, dynamic> toJson() => _$ServiceFaceSyncSnapshotToJson(this);
+}
+
 @JsonSerializable()
 class ServiceTenant {
   /// id

lib/common/models/api/user_api_models.g.dart

@@ -77,6 +77,54 @@ Map<String, dynamic> _$ServiceAsyncFaceToJson(ServiceAsyncFace instance) =>
       'delFlag': JsonTool.booleanToString(instance.delFlag),
     };
 
+ServiceFaceSyncRecord _$ServiceFaceSyncRecordFromJson(
+        Map<String, dynamic> json) =>
+    ServiceFaceSyncRecord(
+      id: JsonTool.anyToRequiredString(json['id']),
+      sampleId: JsonTool.anyToRequiredString(json['sampleId']),
+      userId: JsonTool.anyToRequiredString(json['userId']),
+      username: json['username'] as String?,
+      deptId: JsonTool.anyToRequiredString(json['deptId']),
+      deptName: json['deptName'] as String?,
+      faceImg: json['faceImg'] as String?,
+      sourceUpdatedAt: json['sourceUpdatedAt'] == null
+          ? null
+          : DateTime.parse(json['sourceUpdatedAt'] as String),
+    );
+
+Map<String, dynamic> _$ServiceFaceSyncRecordToJson(
+        ServiceFaceSyncRecord instance) =>
+    <String, dynamic>{
+      'id': JsonTool.stringToInt(instance.id),
+      'sampleId': JsonTool.stringToInt(instance.sampleId),
+      'userId': JsonTool.stringToInt(instance.userId),
+      'username': instance.username,
+      'deptId': JsonTool.stringToInt(instance.deptId),
+      'deptName': instance.deptName,
+      'faceImg': instance.faceImg,
+      'sourceUpdatedAt': instance.sourceUpdatedAt?.toIso8601String(),
+    };
+
+ServiceFaceSyncSnapshot _$ServiceFaceSyncSnapshotFromJson(
+        Map<String, dynamic> json) =>
+    ServiceFaceSyncSnapshot(
+      records: (json['records'] as List<dynamic>)
+          .map((e) => ServiceFaceSyncRecord.fromJson(e as Map<String, dynamic>))
+          .toList(),
+      nextAfterId: JsonTool.anyToRequiredString(json['nextAfterId']),
+      hasMore: json['hasMore'] as bool,
+      snapshotMaxId: JsonTool.anyToRequiredString(json['snapshotMaxId']),
+    );
+
+Map<String, dynamic> _$ServiceFaceSyncSnapshotToJson(
+        ServiceFaceSyncSnapshot instance) =>
+    <String, dynamic>{
+      'records': instance.records,
+      'nextAfterId': JsonTool.stringToInt(instance.nextAfterId),
+      'hasMore': instance.hasMore,
+      'snapshotMaxId': JsonTool.stringToInt(instance.snapshotMaxId),
+    };
+
 ServiceTenant _$ServiceTenantFromJson(Map<String, dynamic> json) =>
     ServiceTenant(
       id: json['id'] as String?,