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