极简接口定义和响应定义，支持更多的解析器

apps/im_app/lib/data/remote/get_profile_request.dart

@@ -6,28 +6,30 @@ import '../../../domain/entities/user.dart';
 
 part 'get_profile_request.g.dart';
 
-/// # /user/profile — 获取用户资料（GET 请求示例）
+/// # /user/profile — 获取用户资料（GET 请求）
 ///
-/// 演示：GET 请求 + 无 body 参数的模式。
-/// GET 请求的 toJson() 结果会自动作为 URL query parameters 发送。
+/// GET 请求无 body，`toJson()` 结果自动作为 URL query parameters 发送。
+/// 如需 query 参数（如分页），直接在类中添加字段，生成器自动序列化。
 ///
 /// ## 数据流位置
 ///
 /// ```
 /// UserRepositoryImpl.getProfile()
-///   → _client.executeRequest( ★ GetProfileRequest ★ )     ← 你在这里
+///   → _client.executeRequest( ★ GetProfileRequest ★ )    ← 你在这里
 ///     → 服务端 GET /user/profile
-///     → 响应 JSON → ★ ProfileData ★                       ← 也在这里
-///       → ProfileData.toEntity() → User
+///     → SDK 内部 ApiResponseWrapper 拆包 { code, message, data }
+///       → ★ ProfileResponse ★ = data 字段                 ← 也在这里
+///         → ProfileResponse.toEntity() → User
 /// ```
 
 // ─────────────────────────────────────────────
 //  Response DTO
 // ─────────────────────────────────────────────
 
-/// 用户资料响应 DTO（只需反序列化，禁止生成无用的 toJson）
-@JsonSerializable(createToJson: false)
-class ProfileData {
+/// 用户资料接口的业务响应数据（对应服务端 `data` 字段）。
+///
+/// `{ code, message }` 由 SDK 内部的 `ApiResponseWrapper` 统一处理。纯 Dart 类，无需任何注解。
+class ProfileResponse {
   final int uid;
   final String uuid;
   @JsonKey(name: 'last_online')
@@ -54,7 +56,7 @@ class ProfileData {
   final int channelGroupId;
   final String hint;
 
-  const ProfileData({
+  const ProfileResponse({
     required this.uid,
     required this.uuid,
     required this.lastOnline,
@@ -74,10 +76,6 @@ class ProfileData {
     required this.hint,
   });
 
-  factory ProfileData.fromJson(Map<String, dynamic> json) =>
-      _$ProfileDataFromJson(json);
-
-  /// DTO → Domain Entity
   User toEntity() => User(
     uid: uid,
     uuid: uuid,
@@ -104,16 +102,12 @@ class ProfileData {
 // ─────────────────────────────────────────────
 
 /// 获取用户资料请求（GET，无参数）
-///
-/// GET 请求无 body，mixin 自动生成 toJson() → 空 map。
-/// 如需 query 参数（如分页），添加字段即可，
-/// toJson() 会自动将字段序列化为 URL query string。
 @ApiRequest(
   path: ApiPaths.userProfile,
   method: HttpMethod.get,
-  responseType: ProfileData,
+  responseType: ProfileResponse,
 )
-class GetProfileRequest extends ApiRequestable<ProfileData>
+class GetProfileRequest extends ApiRequestable<ProfileResponse>
     with _$GetProfileRequestApi {
   GetProfileRequest();
 }

apps/im_app/lib/data/remote/login_request.dart

@@ -12,17 +12,20 @@ part 'login_request.g.dart';
 ///
 /// ```
 /// AuthRepositoryImpl.login(email, password)
-///   → _client.executeRequest( ★ LoginRequest ★ )     ← 你在这里
+///   → _client.executeRequest( ★ LoginRequest ★ )         ← 你在这里
 ///     → 服务端 POST /auth/login
-///     → 响应 JSON → ★ LoginResponse ★                ← 也在这里
-///       → LoginResponse.toEntity() → User
+///     → SDK 内部 ApiResponseWrapper 拆包 { code, message, data }
+///       → ★ LoginResponse ★ = data 字段，T in APIResponseWrapper<T>  ← 也在这里
+///         → LoginResponse.toEntity() → User
 /// ```
 
 // ─────────────────────────────────────────────
 //  Response DTO
 // ─────────────────────────────────────────────
 
-@JsonSerializable(createToJson: false)
+/// 登录响应中的用户档案，嵌套在 [LoginResponse.profile] 中。
+///
+/// 纯 Dart 类，无需任何注解。`_$LoginProfileFromJson` 由生成器从 `@ApiRequest` 声明中自动推导生成。
 class LoginProfile {
   final int uid;
   final String uuid;
@@ -70,9 +73,6 @@ class LoginProfile {
     required this.hint,
   });
 
-  factory LoginProfile.fromJson(Map<String, dynamic> json) =>
-      _$LoginProfileFromJson(json);
-
   User toEntity() => User(
     uid: uid,
     uuid: uuid,
@@ -94,8 +94,11 @@ class LoginProfile {
   );
 }
 
-@JsonSerializable(createToJson: false, explicitToJson: true)
-class LoginData {
+/// 登录接口的业务响应数据（对应服务端 `data` 字段，即 T in `APIResponseWrapper<T>`）。
+///
+/// `{ code, message }` 由 SDK 内部的 `ApiResponseWrapper` 统一处理，
+/// App 层只接触此类，不感知 envelope 结构。纯 Dart 类，无需任何注解。
+class LoginResponse {
   @JsonKey(name: 'account_id')
   final String accountId;
   final LoginProfile profile;
@@ -109,7 +112,7 @@ class LoginData {
   @JsonKey(name: 'login_data')
   final String loginData;
 
-  const LoginData({
+  const LoginResponse({
     required this.accountId,
     required this.profile,
     required this.nonce,
@@ -119,31 +122,9 @@ class LoginData {
     required this.loginData,
   });
 
-  factory LoginData.fromJson(Map<String, dynamic> json) =>
-      _$LoginDataFromJson(json);
-
   User toEntity() => profile.toEntity();
 }
 
-/// Top-level envelope: { "code": 0, "message": "OK", "data": { ... } }
-@JsonSerializable(createToJson: false, explicitToJson: true)
-class LoginResponse {
-  final int code;
-  final String message;
-  final LoginData data;
-
-  const LoginResponse({
-    required this.code,
-    required this.message,
-    required this.data,
-  });
-
-  factory LoginResponse.fromJson(Map<String, dynamic> json) =>
-      _$LoginResponseFromJson(json);
-
-  User toEntity() => data.toEntity();
-}
-
 // ─────────────────────────────────────────────
 //  Request
 // ─────────────────────────────────────────────
@@ -152,9 +133,7 @@ class LoginResponse {
 ///
 /// `@ApiRequest` 一个注解搞定一切：
 /// - mixin 自动生成 path / method / requestType / includeToken / toJson
-/// - toJson 只序列化类自身字段（email, password），不含继承属性
-/// - Response 的 fromJson 在 parameters getter 中自动注册
-/// - 无需 @JsonSerializable，无需手写 fromJson / toJson
+/// - parameters getter 自动注册 `_$LoginResponseFromJson` 到 SDK 全局注册表
 @ApiRequest(
   path: ApiPaths.authLogin,
   method: HttpMethod.post,

apps/im_app/lib/data/remote/logout_request.dart

@@ -2,14 +2,14 @@ import 'package:networks_sdk/networks_sdk.dart';
 
 import '../../../core/foundation/api_paths.dart';
 
-/// # /auth/logout — 登出接口（无响应数据示例）
+part 'logout_request.g.dart';
+
+/// # /auth/logout — 登出接口（无响应数据）
 ///
-/// 演示：POST 请求 + 无 Response DTO 的模式。
 /// 服务端返回 `{"code": 0, "message": "ok"}` 无 data 字段，
 /// `executeRequest` 返回 null，调用方直接 await 即可。
 ///
-/// 此接口不使用 @ApiRequest 注解，直接实现 ApiRequestable，
-/// 演示手动实现方式（适用于不需要代码生成器的简单接口）。
+/// `responseType` 省略 → 生成器跳过 `fromJson` 注册，mixin 泛型为 `void`。
 ///
 /// ## 数据流位置
 ///
@@ -17,16 +17,9 @@ import '../../../core/foundation/api_paths.dart';
 /// AuthRepositoryImpl.logout()
 ///   → _client.executeRequest( ★ LogoutRequest ★ )     ← 你在这里
 ///     → 服务端 POST /auth/logout
-///     → 响应 {"code": 0, "message": "ok"} → null
+///     → 响应 {"code": 0, "message": "ok"} → null（无 data）
 /// ```
-class LogoutRequest extends ApiRequestable<void> {
-  @override
-  String get path => ApiPaths.authLogout;
-
-  @override
-  HttpMethod get method => HttpMethod.post;
-
-  /// 登出不需要请求体参数
-  @override
-  Map<String, dynamic> toJson() => {};
+@ApiRequest(path: ApiPaths.authLogout, method: HttpMethod.post)
+class LogoutRequest extends ApiRequestable<void> with _$LogoutRequestApi {
+  LogoutRequest();
 }

apps/im_app/lib/data/remote/upload_file_request.dart

@@ -32,8 +32,7 @@ part 'upload_file_request.g.dart';
 //  Response DTO
 // ─────────────────────────────────────────────
 
-/// 文件上传响应 DTO（只需反序列化，禁止生成无用的 toJson）
-@JsonSerializable(createToJson: false)
+/// 文件上传接口的业务响应数据（对应服务端 `data` 字段）。纯 Dart 类，无需任何注解。
 class UploadResult {
   final String url;
 
@@ -41,9 +40,6 @@ class UploadResult {
   final String fileId;
 
   const UploadResult({required this.url, required this.fileId});
-
-  factory UploadResult.fromJson(Map<String, dynamic> json) =>
-      _$UploadResultFromJson(json);
 }
 
 // ═════════════════════════════════════════════

apps/im_app/lib/data/repositories/auth_repository_impl.dart

@@ -8,7 +8,7 @@ import '../remote/logout_request.dart';
 /// 认证 Repository 实现
 ///
 /// implements [AuthRepository] 接口（domain/repositories/ 中定义）。
-/// 直接使用 [ApiClient] 发送请求，将 DTO 转为 Domain Entity。
+/// 直接使用 [NetworksSdkApi] 发送请求，将 DTO 转为 Domain Entity。
 /// 后续可加 Local DataSource 实现离线缓存。
 ///
 /// ## 数据流位置
@@ -16,11 +16,11 @@ import '../remote/logout_request.dart';
 /// ```
 /// LoginUseCase.execute(email, password)
 ///   → ★ AuthRepositoryImpl.login() ★        ← 你在这里
-///     → ApiClient.executeRequest(LoginRequest)
+///     → NetworksSdkApi.executeRequest(LoginRequest)
 ///       → 服务端 POST /auth/login
-///     ← LoginData（Response DTO）
-///     → onTokenUpdate(token)                  ← 回调写入 Token
-///     ← LoginData.toEntity() → User          ← DTO → Entity 转换在这里
+///     ← LoginResponse（SDK 已拆包 { code, message, data } envelope）
+///     → _onTokenUpdate(accessToken)           ← 回调写入 Token
+///     ← LoginResponse.toEntity() → User       ← DTO → Entity 转换在这里
 ///   ← User（Domain Entity）
 /// ```
 class AuthRepositoryImpl implements AuthRepository {
@@ -43,7 +43,7 @@ class AuthRepositoryImpl implements AuthRepository {
       throw Exception('Login failed: empty response');
     }
 
-    _onTokenUpdate(loginResponse.data.accessToken);
+    _onTokenUpdate(loginResponse.accessToken);
 
     return loginResponse.toEntity();
   }

apps/im_app/lib/features/login/presentation/login_view_model.dart

@@ -1,10 +1,10 @@
 import 'dart:convert';
 
 import 'package:flutter/services.dart';
-import 'package:im_app/data/models/user_dto.dart';
-import 'package:im_app/data/remote/login_request.dart';
-import 'package:networks_sdk/networks_sdk.dart';
 import 'package:im_app/app/di/db_provider.dart';
+import 'package:im_app/data/models/user_dto.dart';
+import 'package:im_app/domain/entities/user.dart';
+import 'package:networks_sdk/networks_sdk.dart';
 import 'package:riverpod_annotation/riverpod_annotation.dart';
 import 'package:storage_sdk/storage_sdk.dart';
 
@@ -44,7 +44,7 @@ part 'login_view_model.g.dart';
 ///     → LoginUseCase.execute()                     ← 格式校验 + 调 Repository
 ///       → AuthRepository.login()
 ///         → _client.executeRequest(LoginRequest)
-///       ← LoginData → User
+///       ← LoginResponse → User
 ///     ← User
 ///   → state = state.copyWith(user: user)           ← 更新状态
 /// View: ref.watch → 自动 rebuild                    ← UI 刷新
@@ -67,11 +67,33 @@ class LoginViewModel extends _$LoginViewModel {
       final storageApi = ref.read(storageSdkProvider);
       final storageLifeCycle = storageApi as StorageSdkLifecycle;
 
-      // 读取 mock 数据
+      // 读取 mock 数据（loginData.json 结构: { code, message, data: {...} }）
+      // 手动拆包 data 字段，对应 SDK 内部 ApiResponseWrapper 的行为
       final raw = await rootBundle.loadString('assets/loginData.json');
       final json = jsonDecode(raw) as Map<String, dynamic>;
-      final loginResponse = LoginResponse.fromJson(json);
-      final user = loginResponse.data.toEntity();
+      final data = json['data'] as Map<String, dynamic>;
+      final profile = data['profile'] as Map<String, dynamic>;
+      // 生成器生成的 _$XFromJson 是 library 私有函数，外部不可调用。
+      // Demo 场景直接从 JSON 字段构建 User，不依赖生成的 fromJson。
+      final user = User(
+        uid: profile['uid'] as int,
+        uuid: profile['uuid'] as String,
+        lastOnline: profile['last_online'] as int,
+        profilePic: profile['profile_pic'] as String,
+        profilePicGaussian: profile['profile_pic_gaussian'] as String,
+        nickname: profile['nickname'] as String,
+        contact: profile['contact'] as String,
+        countryCode: profile['country_code'] as String,
+        email: profile['email'] as String,
+        recoveryEmail: profile['recovery_email'] as String,
+        username: profile['username'] as String,
+        bio: profile['bio'] as String,
+        relationship: profile['relationship'] as int,
+        userAlias: profile['user_alias'] as String?,
+        channelId: profile['channel_id'] as int,
+        channelGroupId: profile['channel_group_id'] as int,
+        hint: profile['hint'] as String,
+      );
 
       // 先完成 DB 操作，再标记登录状态（失败时不会误标为已登录）
       await storageLifeCycle.openDatabase(user.uid);

apps/im_app/lib/features/login/usecases/login_usecase.dart

@@ -28,9 +28,9 @@ import '../../../domain/repositories/auth_repository.dart';
 ///     → AuthRepository.login()
 ///       → AuthRepositoryImpl.login()
 ///         → _client.executeRequest(LoginRequest)
-///       ← LoginData（DTO）
-///       → _onTokenUpdate(token)               ← 回调写入 Token（内存 + 持久化，由 Provider 层组合）
-///       ← LoginData.toEntity() → User
+///       ← LoginResponse（SDK 已拆包 envelope）
+///       → _onTokenUpdate(accessToken)         ← 回调写入 Token（内存 + 持久化，由 Provider 层组合）
+///       ← LoginResponse.toEntity() → User
 ///     → SocketManager.connect(token)           ← 登录后连接 WebSocket
 ///     → StorageSdkApi.openDatabase(user.id)    ← 按用户 id 打开本地库
 ///   ← User
@@ -41,17 +41,18 @@ class LoginUseCase {
   final ApiConfig _apiConfig;
   final StorageSdkApi _storageApi;
 
-  StorageSdkLifecycle get _storageLifeCycle => _storageApi as StorageSdkLifecycle;
+  StorageSdkLifecycle get _storageLifeCycle =>
+      _storageApi as StorageSdkLifecycle;
 
   LoginUseCase({
     required AuthRepository authRepository,
     required SocketManager socketManager,
     required ApiConfig apiConfig,
     required StorageSdkApi storageApi,
-  })  : _authRepository = authRepository,
-        _socketManager = socketManager,
-        _apiConfig = apiConfig,
-        _storageApi = storageApi;
+  }) : _authRepository = authRepository,
+       _socketManager = socketManager,
+       _apiConfig = apiConfig,
+       _storageApi = storageApi;
 
   /// 执行登录
   ///
@@ -72,10 +73,7 @@ class LoginUseCase {
     _validatePassword(password);
 
     // ── 2. 登录 ──
-    final user = await _authRepository.login(
-      email: email,
-      password: password,
-    );
+    final user = await _authRepository.login(email: email, password: password);
 
     // ── 3. 连接 WebSocket ──
     // token 在 Repository 的 _onTokenUpdate 回调中已写入 ApiConfig，