业务更新User所需（企业成员、聊天室群组成员）

apps/im_app/lib/domain/entities/user.dart

@@ -47,6 +47,24 @@ class User {
   final int? configBits;
   final String? hint;
 
+  /// 标记此用户数据是否为部分数据，需要 upsert 而非全字段覆盖。
+  ///
+  /// 由响应解析层设置，Repository 据此决定写入策略：
+  /// - true  → [UserRepository.upsertUser]，仅更新非 null 字段，保留本地已有数据
+  /// - false → [UserRepository.insertOrReplaceUser]，全字段覆盖（默认）
+  ///
+  /// 注意：此字段仅用于内存传递，不会被持久化到 DB。
+  final bool requireUpsert;
+
+  /// TODO(contacts): 添加 localName / localPhoneNumbers，关联本地通讯录。
+  ///   这两个字段是设备侧数据，不应持久化到服务端 payload。
+  ///
+  /// TODO(history): status 和 created_at 仅出现在历史用户记录中（如审计日志）。
+  ///   建议用独立的 UserHistory 实体承载，避免污染此 Domain 模型。
+  ///
+  /// TODO(online): objectMgr.onlineMgr.updateOnlineTime() 原先在 fromJson() 内
+  ///   作为副作用调用。不要在此处复现——副作用应在 Repository 或 UseCase 层处理。
+
   const User({
     required this.uid,
     this.uuid,
@@ -81,9 +99,13 @@ class User {
     this.publicKey,
     this.configBits,
     this.hint,
+    this.requireUpsert = false,
   });
 
-  /// 直接从网络 JSON 创建 Domain 实体
+  /// 直接从网络 JSON 创建 Domain 实体。
+  ///
+  /// [requireUpsert] 默认 false，如响应解析层判断为部分数据，
+  /// 可在调用后通过 copyWith(requireUpsert: true) 标记。
   factory User.fromJson(Map<String, dynamic> json) => User(
     uid: json['uid'] as int,
     uuid: json['uuid'],
@@ -120,7 +142,10 @@ class User {
     hint: json['hint'],
   );
 
-  /// 仅更新部分字段
+  /// 仅更新部分字段，其余保持不变。
+  ///
+  /// 注意：[requireUpsert] 不会随其他字段自动继承，
+  /// 需要显式传入以避免意外的写入策略变更。
   User copyWith({
     int? uid,
     String? uuid,
@@ -155,6 +180,7 @@ class User {
     String? publicKey,
     int? configBits,
     String? hint,
+    bool? requireUpsert,
   }) {
     return User(
       uid: uid ?? this.uid,
@@ -191,6 +217,7 @@ class User {
       publicKey: publicKey ?? this.publicKey,
       configBits: configBits ?? this.configBits,
       hint: hint ?? this.hint,
+      requireUpsert: requireUpsert ?? this.requireUpsert,
     );
   }
 }