From 0ee2c8c63cad5ee7dacf8ede29436f783e0c3300 Mon Sep 17 00:00:00 2001 From: Cody Date: Sat, 7 Mar 2026 14:58:10 +0800 Subject: [PATCH 1/5] =?UTF-8?q?=E4=BC=98=E5=8C=96=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=EF=BC=8C=E4=BF=AE=E5=A4=8D=20demo=20bug?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1，network 框架完善 2，websocket 机制完善 3，设计文档整理到架构文档 4，脚本，配置完善 --- Doc/IM_App_架构设计.html | 320 +++++++++++++----- apps/im_app/android/settings.gradle.kts | 1 + apps/im_app/ios/Podfile | 5 + .../ios/Runner.xcodeproj/project.pbxproj | 13 +- apps/im_app/ios/Runner/AppDelegate.swift | 10 +- apps/im_app/lib/app/di/network_provider.dart | 162 +++++++-- apps/im_app/lib/core/foundation/errors.dart | 57 ++++ apps/im_app/lib/core/foundation/utils.dart | 32 ++ .../lib/core/services/socket_manager.dart | 122 +++++-- apps/im_app/lib/core/ui/base/assets.dart | 30 ++ apps/im_app/lib/core/ui/base/icons.dart | 44 +++ .../presentation/chat_db_test_view_model.dart | 16 +- .../features/chat/view/chat_detail_page.dart | 5 +- .../lib/features/chat/view/chat_page.dart | 28 +- .../features/contact/view/contact_page.dart | 5 +- .../lib/features/login/di/auth_providers.dart | 6 +- .../login/presentation/login_view_model.dart | 10 +- apps/im_app/macos/Podfile | 5 +- .../macos/Runner.xcodeproj/project.pbxproj | 18 +- apps/im_app/pubspec.yaml | 4 + .../cipher_guard_sdk/android/build.gradle | 66 ---- .../cipher_guard_sdk/android/build.gradle.kts | 71 ++++ .../ios/Classes/CipherGuardSdkPlugin.swift | 2 +- .../ios/cipher_guard_sdk.podspec | 2 +- .../encryption_flutter_service.dart | 143 ++++---- packages/im_log_sdk/android/build.gradle.kts | 24 +- .../ios/Classes/ImLogSdkPlugin.swift | 2 +- packages/im_log_sdk/ios/im_log_sdk.podspec | 2 +- .../macos/Classes/ImLogSdkPlugin.swift | 2 +- packages/im_log_sdk/macos/im_log_sdk.podspec | 4 +- packages/l10n_sdk/android/build.gradle | 66 ---- packages/l10n_sdk/android/build.gradle.kts | 71 ++++ .../l10n_sdk/ios/Classes/L10nSdkPlugin.swift | 2 +- packages/l10n_sdk/ios/l10n_sdk.podspec | 2 +- packages/media_sdk/android/build.gradle | 66 ---- packages/media_sdk/android/build.gradle.kts | 71 ++++ .../ios/Classes/MediaSdkPlugin.swift | 2 +- packages/media_sdk/ios/media_sdk.podspec | 2 +- packages/networks_sdk/android/build.gradle | 66 ---- .../networks_sdk/android/build.gradle.kts | 71 ++++ .../ios/Classes/NetworksSdkPlugin.swift | 2 +- .../networks_sdk/ios/networks_sdk.podspec | 2 +- packages/networks_sdk/lib/networks_sdk.dart | 6 +- .../src/data/datasources/http/api_client.dart | 16 +- .../interceptor/encryption_interceptor.dart | 114 +++++++ .../http/interceptor/retry_interceptor.dart | 107 +++--- .../http/token_refresh_manager.dart | 152 +++++++++ ...etworks_sdk_method_channel_datasource.dart | 231 +++++++++++-- .../datasources/socket/socket_client.dart | 169 +++++++-- .../networks_messaging_repository_impl.dart | 23 +- .../networks_sdk_repository_impl.dart | 38 ++- .../lib/src/domain/entities/api_error.dart | 6 +- .../src/domain/entities/api_request_type.dart | 9 + .../domain/entities/encrypted_request.dart | 55 +++ .../networks_messaging_repository.dart | 28 +- .../repositories/networks_sdk_repository.dart | 24 +- .../facade/networks_messaging_api.dart | 61 ++-- .../presentation/facade/networks_sdk_api.dart | 68 +++- .../src/presentation/wiring/api_config.dart | 79 ++++- .../wiring/network_callbacks.dart | 100 +++++- .../wiring/networks_messaging_api_impl.dart | 23 +- .../wiring/networks_sdk_api_impl.dart | 27 +- .../presentation/wiring/socket_config.dart | 60 +++- .../notification_sdk/android/build.gradle | 66 ---- .../notification_sdk/android/build.gradle.kts | 71 ++++ .../ios/Classes/NotificationSdkPlugin.swift | 2 +- .../ios/notification_sdk.podspec | 2 +- packages/protocol_sdk/android/build.gradle | 66 ---- .../protocol_sdk/android/build.gradle.kts | 71 ++++ .../ios/Classes/ProtocolSdkPlugin.swift | 2 +- .../protocol_sdk/ios/protocol_sdk.podspec | 2 +- packages/rtc_sdk/android/build.gradle | 66 ---- packages/rtc_sdk/android/build.gradle.kts | 71 ++++ .../rtc_sdk/ios/Classes/RtcSdkPlugin.swift | 2 +- packages/rtc_sdk/ios/rtc_sdk.podspec | 2 +- packages/storage_sdk/android/build.gradle | 66 ---- packages/storage_sdk/android/build.gradle.kts | 71 ++++ .../ios/Classes/StorageSdkPlugin.swift | 2 +- packages/storage_sdk/ios/storage_sdk.podspec | 2 +- pubspec.lock | 38 ++- pubspec.yaml | 6 + scripts/new_sdk.sh | 111 ++++++ 82 files changed, 2704 insertions(+), 1045 deletions(-) create mode 100644 apps/im_app/lib/core/ui/base/assets.dart create mode 100644 apps/im_app/lib/core/ui/base/icons.dart delete mode 100644 packages/cipher_guard_sdk/android/build.gradle create mode 100644 packages/cipher_guard_sdk/android/build.gradle.kts delete mode 100644 packages/l10n_sdk/android/build.gradle create mode 100644 packages/l10n_sdk/android/build.gradle.kts delete mode 100644 packages/media_sdk/android/build.gradle create mode 100644 packages/media_sdk/android/build.gradle.kts delete mode 100644 packages/networks_sdk/android/build.gradle create mode 100644 packages/networks_sdk/android/build.gradle.kts create mode 100644 packages/networks_sdk/lib/src/data/datasources/http/interceptor/encryption_interceptor.dart create mode 100644 packages/networks_sdk/lib/src/data/datasources/http/token_refresh_manager.dart create mode 100644 packages/networks_sdk/lib/src/domain/entities/encrypted_request.dart delete mode 100644 packages/notification_sdk/android/build.gradle create mode 100644 packages/notification_sdk/android/build.gradle.kts delete mode 100644 packages/protocol_sdk/android/build.gradle create mode 100644 packages/protocol_sdk/android/build.gradle.kts delete mode 100644 packages/rtc_sdk/android/build.gradle create mode 100644 packages/rtc_sdk/android/build.gradle.kts delete mode 100644 packages/storage_sdk/android/build.gradle create mode 100644 packages/storage_sdk/android/build.gradle.kts diff --git a/Doc/IM_App_架构设计.html b/Doc/IM_App_架构设计.html index bfedfb8..8cb14bf 100644 --- a/Doc/IM_App_架构设计.html +++ b/Doc/IM_App_架构设计.html @@ -883,13 +883,16 @@ flowchart TD │ ├── data/ │ │ ├── datasources/ │ │ │ ├── http/ -│ │ │ │ ├── api_client.dart # Dio REST 客户端 +│ │ │ │ ├── api_client.dart # Dio REST 客户端 +│ │ │ │ ├── token_refresh_manager.dart # Token 刷新管理（竞态安全 + 超时 + 时间窗口复用） │ │ │ │ └── interceptor/ -│ │ │ │ ├── auth_interceptor.dart # Token + 默认 header 注入 -│ │ │ │ ├── retry_interceptor.dart # Token 刷新 + 瞬态错误重试 -│ │ │ │ └── logging_interceptor.dart # 请求/响应日志 -│ │ │ └── socket/ -│ │ │ └── socket_client.dart # WebSocket 长连接（心跳/重连/Stream） +│ │ │ │ ├── auth_interceptor.dart # Token + 默认 header 注入 +│ │ │ │ ├── encryption_interceptor.dart # 加密拦截器（预留给 cipher_guard_sdk） +│ │ │ │ ├── retry_interceptor.dart # Token 刷新 + 瞬态错误重试 + 业务错误钩子 +│ │ │ │ └── logging_interceptor.dart # 请求/响应日志 +│ │ │ ├── socket/ +│ │ │ │ └── socket_client.dart # WebSocket 长连接（心跳/重连/Stream/加密钩子） +│ │ │ └── networks_sdk_method_channel_datasource.dart # 统一执行入口 │ │ ├── dto/ │ │ │ ├── api_requestable.dart # 请求基类 + fromJson 注册表 │ │ │ └── api_response_wrapper.dart # { code, message/msg, data } 信封解析 @@ -898,11 +901,12 @@ flowchart TD │ │ └── networks_messaging_repository_impl.dart │ ├── domain/ │ │ ├── entities/ -│ │ │ ├── api_error.dart # @freezed HTTP 错误联合类型 +│ │ │ ├── api_error.dart # @freezed HTTP 错误联合类型（7 变体） +│ │ │ ├── encrypted_request.dart # 加密请求结果数据类 │ │ │ ├── socket_error.dart # @freezed WebSocket 错误联合类型 │ │ │ ├── socket_connection_state.dart # 连接状态 enum │ │ │ ├── http_method.dart # GET/POST/PUT/DELETE/PATCH -│ │ │ └── api_request_type.dart # request/login/upload +│ │ │ └── api_request_type.dart # request/login/upload/stream/download │ │ └── repositories/ │ │ ├── networks_sdk_repository.dart │ │ └── networks_messaging_repository.dart @@ -911,9 +915,9 @@ flowchart TD │ │ ├── networks_sdk_api.dart # HTTP 公开 API 接口 │ │ └── networks_messaging_api.dart # WebSocket 公开 API 接口 │ └── wiring/ -│ ├── api_config.dart # HTTP 配置（baseURL/Token/回调） -│ ├── socket_config.dart # WebSocket 配置（心跳/重连策略） -│ ├── network_callbacks.dart # 回调类型定义 +│ ├── api_config.dart # HTTP 配置（baseURL/Token/回调/加密/重试） +│ ├── socket_config.dart # WebSocket 配置（心跳/重连/加密钩子） +│ ├── network_callbacks.dart # 回调类型定义（认证/加密/业务错误/下载/WS） │ ├── networks_sdk_core.dart │ ├── networks_sdk_api_impl.dart │ ├── networks_messaging_api_impl.dart @@ -1670,7 +1674,7 @@ final viewModel = ref.read(chatViewModelProvider.notifier); // viewModel 类型 
// Riverpod DevTools 可以看到完整的依赖图
 ChatViewModel
   ├─ chatRepositoryProvider
-  │   ├─ apiClientProvider
+  │   ├─ networkSdkApiProvider
   │   └─ messageLocalDataSourceProvider
   └─ sendMessageUseCaseProvider
       └─ chatRepositoryProvider
@@ -2187,8 +2191,8 @@ extension APIRequestableDefaults<T> on APIRequestable<T> {
 
 
/// 执行 API 请求 - 唯一的请求入口
 Future<T?> executeRequest<T>(Ref ref, APIRequestable<T> request) async {
-  final dio = ref.read(apiClientProvider);
-  final config = ref.read(aPIConfigurationProvider);
+  final client = ref.read(networkSdkApiProvider);
+  final config = ref.read(apiConfigProvider);
 
   // 1. 检查网络连接
   if (!networkManager.isNetworkAvailable) {
@@ -2646,18 +2650,20 @@ final apiConfigProvider = Provider<ApiConfig>((ref) {
   );
 });
 
-/// 2. API 客户端（内部自动挂载 Auth / Retry / Logging 拦截器）
-final apiClientProvider = Provider<ApiClient>((ref) {
-  return ApiClient(config: ref.read(apiConfigProvider));
+/// 2. Networks SDK API Provider（全局单例，Facade 接口）
+/// 内部自动挂载 AuthInterceptor / EncryptionInterceptor / RetryInterceptor / LoggingInterceptor
+final networkSdkApiProvider = Provider<NetworksSdkApi>((ref) {
+  final config = ref.read(apiConfigProvider);
+  return NetworksSdkWiring.build(config: config);
 });
 
 // ── features/auth/di/auth_providers.dart ── （Auth 模块完整 DI 链路）
 
-/// 3. Repository（注入 domain 接口类型，ViewModel 不感知具体实现）
+/// 3. Repository（注入 Facade 接口类型，ViewModel 不感知具体实现）
 final authRepositoryProvider = Provider<AuthRepository>((ref) {
   final apiConfig = ref.read(apiConfigProvider);
   return AuthRepositoryImpl(
-    client: ref.read(apiClientProvider),          // 直接注入 ApiClient
+    client: ref.read(networkSdkApiProvider),       // 注入 Facade 接口
     onTokenUpdate: (token) {
       apiConfig.updateToken(token);               // 内存（networks_sdk）
       // secureStorage.saveToken(token);          // 持久化（storage_sdk，待接入）
@@ -2707,8 +2713,9 @@ class LoginViewModel extends _$LoginViewModel {
       → Repository: _client.executeRequest(LoginRequest(...))
         → ApiClient.executeRequest()             ← networks_sdk 内部
           → AuthInterceptor                      ← 注入 token + headers
+          → EncryptionInterceptor                ← 加密请求体（预留）
           → Dio.request(baseURL + path, data)    ← 实际 HTTP 请求
-          → RetryInterceptor                     ← token 过期自动刷新重试
+          → RetryInterceptor                     ← token 过期自动刷新重试 + 业务错误钩子
           → LoggingInterceptor                   ← 请求/响应日志
         ← request.decodeResponse(response)       ← 自动解码
           ← ApiResponseWrapper.fromJson          ← 拆 { code, msg, data }
@@ -2987,8 +2994,9 @@ flowchart TD
 │   │       └── auth_guard.dart             # 登录守卫（switch AppRouteName，穷举防漏路由）
 │   │
 │   └── di/                                  # 全局 DI — 手动装配的 Provider
-│       ├── network_provider.dart            # NetworkMonitor + ApiConfig + ApiClient + SocketConfig + SocketClient + SocketManager
-│       └── app_providers.dart               # 全局共享状态（themeModeProvider + AuthNotifier）
+│       ├── network_provider.dart            # NetworkMonitor + ApiConfig + NetworksSdkApi + SocketConfig + SocketClient + SocketManager
+│       ├── db_provider.dart                 # StorageSdkApi（注入 AppDatabase factory）
+│       └── app_providers.dart               # AppInitializer + ThemeModeNotifier + AuthNotifier
 │
 ├── features/                                # 功能模块（垂直切片）：Feature 间禁止直接 import
 │   │
@@ -3022,6 +3030,7 @@ flowchart TD
 │       ├── di/
 │       │   └── settings_providers.dart      # settingsRepositoryProvider（待 storage_sdk 接入）
 │       ├── presentation/
+│       │   ├── settings_view_model.dart     # @riverpod ViewModel（设置页导航）
 │       │   └── theme_view_model.dart        # @riverpod ViewModel（生成 theme_view_model.g.dart）
 │       ├── usecases/
 │       │   └── set_theme_usecase.dart       # 主题切换用例
@@ -3081,6 +3090,8 @@ flowchart TD
     │
     └── ui/                                  # Core UI（设计系统 + 可复用组件）
         ├── base/                            # 设计 Token
+        │   ├── assets.dart                  # 静态资源路径常量（AppAssets：logo / 占位图）
+        │   ├── icons.dart                   # 图标常量（AppIcons：导航 / 操作 / 聊天 / 用户 / 状态）
         │   ├── app_theme.dart               # ThemeData 组装（Light / Dark）
         │   ├── colors.dart                  # 颜色体系（品牌色 / 语义色 / 灰阶）
         │   ├── context_theme_ext.dart       # BuildContext 主题扩展（context.theme / context.colors）
@@ -3172,7 +3183,7 @@ flowchart LR
         direction TB
         Step1["① 用户点击发送按钮"]
         Step2["② ref.read(chatVM.notifier)
.sendMessage(content)"]
-        Step3["③ ViewModel 调用 UseCase
→ Repository → ApiClient"]
+        Step3["③ ViewModel 调用 UseCase
→ Repository → NetworksSdkApi"]
         Step4["④ state = state.copyWith(
messages: [..., newMsg])"]
         Step5["⑤ ref.watch(chatVM) 检测变化
→ ConsumerWidget 自动 rebuild"]
         Step6["⑥ UI 展示最新消息列表"]
@@ -3356,7 +3367,7 @@ abstract class ChatRepository {
 
 // Data 层实现接口
 class ChatRepositoryImpl implements ChatRepository {
-  final ApiClient _client;
+  final NetworksSdkApi _client;
   final MessageLocalDataSource _localDataSource;
 
   @override
@@ -5623,7 +5634,7 @@ flowchart TD
 │       ├── file_storage.dart                   # 文件存储管理
 │       └── image_cache.dart                    # 图片缓存
 │
-├── remote/                                     # Request 文件（一个端点一个文件，Repository 直接调 ApiClient）
+├── remote/                                     # Request 文件（一个端点一个文件，Repository 直接调 NetworksSdkApi）
 │   ├── login_request.dart                      # 登录端点
 │   ├── logout_request.dart                     # 登出端点
 │   ├── send_message_request.dart               # 发消息端点
@@ -5648,17 +5659,17 @@ flowchart TD
     Domain[Domain Layer
domain/repositories/
Repository 接口] -.实现.-> Repo[Data Layer
data/repositories/
Repository 实现]
 
     Repo -->|读取| LocalDS[Local DataSource
data/local/]
-    Repo -->|请求| ApiClient[ApiClient
networks_sdk]
+    Repo -->|请求| SdkApi[NetworksSdkApi
networks_sdk]
     Repo -->|缓存| Cache[Cache Manager
data/cache/]
 
     LocalDS -->|Drift| DB[(Database)]
-    ApiClient -->|HTTP/WebSocket| API[API Server]
+    SdkApi -->|HTTP/WebSocket| API[API Server]
     Cache -->|内存| Memory[Memory Cache]
 
     style Domain fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
     style Repo fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
     style LocalDS fill:#c8e6c9,stroke:#388e3c
-    style ApiClient fill:#c8e6c9,stroke:#388e3c
+    style SdkApi fill:#c8e6c9,stroke:#388e3c
     style Cache fill:#c8e6c9,stroke:#388e3c
 
 
@@ -5686,14 +5697,14 @@ class MessageLocalDataSource {
 
 
    
 
  • 一个端点 = 一个文件：Response DTO + Request 类放在同一文件中
    • 
-
  • Repository 直接调 ApiClient：无需 RemoteDataSource 中间层
    • 
+
  • Repository 直接调 NetworksSdkApi：无需 RemoteDataSource 中间层
    • 
 
  • @ApiRequest 注解 + 代码生成：自动实现 path / method / fromJson 注册
    • 
 

 
 
// 示例：Repository 直接调用 Request
 // data/repositories/message_repository_impl.dart
 class MessageRepositoryImpl implements MessageRepository {
-  final ApiClient _client;
+  final NetworksSdkApi _client;
 
   Future<SendMessageData?> sendMessage({
     required String chatId,
@@ -5758,9 +5769,9 @@ flowchart LR
 
     RepoImpl -->|1. 检查缓存| Cache[Cache]
     RepoImpl -->|2. 读取本地| LocalDS[Local DS]
-    RepoImpl -->|3. 请求远程| ApiClient2[ApiClient]
+    RepoImpl -->|3. 请求远程| SdkApi2[NetworksSdkApi]
 
-    ApiClient2 -->|DTO| RepoImpl
+    SdkApi2 -->|DTO| RepoImpl
     RepoImpl -->|转换| Entity[Entity]
     Entity -->|返回| UC
 
@@ -5884,13 +5895,16 @@ flowchart LR
         ├── data/
         │   ├── datasources/
         │   │   ├── http/
-        │   │   │   ├── api_client.dart          # Dio REST 客户端（executeRequest<T> 唯一入口）
+        │   │   │   ├── api_client.dart              # Dio REST 客户端
+        │   │   │   ├── token_refresh_manager.dart   # Token 刷新管理（竞态安全 + 超时 + 时间窗口复用 + 主动刷新）
         │   │   │   └── interceptor/
-        │   │   │       ├── auth_interceptor.dart    # Token + 默认 header 注入
-        │   │   │       ├── retry_interceptor.dart   # Token 刷新 + 瞬态错误重试
-        │   │   │       └── logging_interceptor.dart # 请求/响应日志
-        │   │   └── socket/
-        │   │       └── socket_client.dart       # WebSocket 长连接（心跳/重连/Stream 输出）
+        │   │   │       ├── auth_interceptor.dart        # Token + 默认 header 注入
+        │   │   │       ├── encryption_interceptor.dart  # 请求加密 / 响应解密（预留给 cipher_guard_sdk）
+        │   │   │       ├── retry_interceptor.dart       # Token 刷新 + 瞬态错误重试 + 业务错误钩子
+        │   │   │       └── logging_interceptor.dart     # 请求/响应日志
+        │   │   ├── socket/
+        │   │   │   └── socket_client.dart           # WebSocket 长连接（心跳/重连/Stream/Token 热更新/加密钩子）
+        │   │   └── networks_sdk_method_channel_datasource.dart  # 统一执行入口（executeRequest / executeDownload）
         │   ├── dto/
         │   │   ├── api_requestable.dart         # 请求基类 + fromJson 注册表 + 解码扩展
         │   │   └── api_response_wrapper.dart    # { code, message/msg, data } 信封解析
@@ -5899,22 +5913,23 @@ flowchart LR
         │       └── networks_messaging_repository_impl.dart
         ├── domain/
         │   ├── entities/
-        │   │   ├── api_error.dart               # @freezed HTTP 错误联合类型
+        │   │   ├── api_error.dart               # @freezed HTTP 错误联合类型（7 变体，含 cancelled）
+        │   │   ├── encrypted_request.dart       # 加密请求结果数据类（path / headers / body 覆盖）
         │   │   ├── socket_error.dart             # @freezed WebSocket 错误联合类型
         │   │   ├── socket_connection_state.dart  # 连接状态 enum
         │   │   ├── http_method.dart              # GET / POST / PUT / DELETE / PATCH
-        │   │   └── api_request_type.dart         # request / login / upload
+        │   │   └── api_request_type.dart         # request / login / upload / stream / download
         │   └── repositories/
         │       ├── networks_sdk_repository.dart
         │       └── networks_messaging_repository.dart
         └── presentation/
             ├── facade/
-            │   ├── networks_sdk_api.dart         # HTTP 公开 API 接口
-            │   └── networks_messaging_api.dart   # WebSocket 公开 API 接口
+            │   ├── networks_sdk_api.dart         # HTTP 公开 API 接口（含 executeDownload）
+            │   └── networks_messaging_api.dart   # WebSocket 公开 API 接口（含 updateToken / sendBytes）
             └── wiring/
-                ├── api_config.dart               # HTTP 配置（baseURL / token / 回调）
-                ├── socket_config.dart            # WebSocket 配置（心跳 / 重连策略）
-                ├── network_callbacks.dart        # 回调类型定义（OnTokenRefresh 等）
+                ├── api_config.dart               # HTTP 配置（baseURL / token / 回调 / 加密 / 重试 / 主动刷新）
+                ├── socket_config.dart            # WebSocket 配置（心跳 / 重连 / 加密钩子 / 压缩）
+                ├── network_callbacks.dart        # 回调类型定义（认证 / 加密 / 业务错误 / 下载进度 / WS 加密）
                 ├── networks_sdk_core.dart
                 ├── networks_sdk_api_impl.dart
                 ├── networks_messaging_api_impl.dart
@@ -5928,7 +5943,7 @@ flowchart LR
 职责SDK (networks_sdk)App 层 (im_app)
 
 
-Dio 管理ApiClient 内部创建管理构造 ApiClient 传入 config
+Dio 管理ApiClient 内部创建管理通过 NetworksSdkWiring.build(config:) 创建
 baseURLApiConfig.baseURLAppConfig.apiBaseUrl 提供初始值
 Token 存储ApiConfig.token（内存）安全存储、持久化
 Token 刷新检测过期 → 调 onTokenRefresh提供回调实现
@@ -5941,7 +5956,7 @@ flowchart LR
 WebSocket 重连指数退避自动重连（1s→2s→4s→8s→16s→30s）无需关心
 WebSocket 生命周期提供 onEnterForeground/BackgroundApp 层调用（AppLifecycleListener）
 WebSocket 消息解析JSON.decode → Stream 输出App 层按 type 过滤 + DTO 解析
-Riverpod无依赖Provider 包装 ApiClient / SocketClient
+Riverpod无依赖Provider 包装 NetworksSdkApi / SocketClient
 
 
 
@@ -5968,7 +5983,7 @@ flowchart LR
 
  • 一个端点 = 一个 Request 文件：Response DTO + Request 类放在同一文件中
    • 
 
  • Response DTO 必须有 toEntity()：统一 DTO → Domain Entity 的转换入口
    • 
 
  • 持久化 DTO 和 Response DTO 分开：Response DTO（XxxData）在 request 文件中，持久化 DTO（XxxDto）在 data/models/
    • 
-
  • 禁止跳层：ViewModel → Repository（→ UseCase 按需）→ ApiClient，每层职责明确
    • 
+
  • 禁止跳层：ViewModel → Repository（→ UseCase 按需）→ NetworksSdkApi，每层职责明确
    • 
 
 
 
    傻瓜式教程：从零开始定义并发送一个接口
    
@@ -6112,10 +6127,10 @@ class LoginRequest extends ApiRequestable<LoginData>  // ← 固定写法
 
 
 
-
    第 2 步：在 Repository 中调用 ApiClient，转为 Domain Entity
    
+
    第 2 步：在 Repository 中调用 NetworksSdkApi，转为 Domain Entity
    
 
 
    在哪写：lib/data/repositories/auth_repository_impl.dart
    
-
    做什么：直接调 ApiClient.executeRequest → 拿到 DTO → 回调写 Token → 转为 Domain Entity → 返回。
    
+
    做什么：调 NetworksSdkApi.executeRequest → 拿到 DTO → 回调写 Token → 转为 Domain Entity → 返回。
    
 
 
    import 'package:networks_sdk/networks_sdk.dart';
 import '../../domain/entities/user.dart';
@@ -6123,11 +6138,11 @@ import '../../domain/repositories/auth_repository.dart';
 import '../remote/login_request.dart';
 
 class AuthRepositoryImpl implements AuthRepository {
-  final ApiClient _client;                        // ← 直接注入 ApiClient
+  final NetworksSdkApi _client;                   // ← 注入 Facade 接口
   final void Function(String?) _onTokenUpdate;    // ← 回调，由 Provider 层组合
 
   AuthRepositoryImpl({
-    required ApiClient client,
+    required NetworksSdkApi client,
     required void Function(String?) onTokenUpdate,
   })  : _client = client,
         _onTokenUpdate = onTokenUpdate;
@@ -6137,7 +6152,7 @@ class AuthRepositoryImpl implements AuthRepository {
     required String email,
     required String password,
   }) async {
-    // 1. 直接调 ApiClient，构造请求 → 发 HTTP → 自动解码 → 返回 DTO
+    // 1. 调 NetworksSdkApi，构造请求 → 发 HTTP → 自动解码 → 返回 DTO
     final LoginData? loginData = await _client.executeRequest(
       LoginRequest(email: email, password: password),
     );
@@ -6162,15 +6177,15 @@ class AuthRepositoryImpl implements AuthRepository {
 
    3.1 注册 Provider（DI 装配）
    
 
 
    在哪写：lib/features/{模块}/di/{模块}_providers.dart
    
-
    做什么：在 Feature 目录下创建 Provider 文件，注册该模块的 DI 链路（Repository → UseCase 按需）。app/di/ 只提供 SDK 基础设施（ApiConfig / ApiClient），业务模块的 Provider 内聚在 Feature 目录下。
    
+
    做什么：在 Feature 目录下创建 Provider 文件，注册该模块的 DI 链路（Repository → UseCase 按需）。app/di/ 只提供 SDK 基础设施（ApiConfig / NetworksSdkApi），业务模块的 Provider 内聚在 Feature 目录下。
    
 
 
    // ── features/auth/di/auth_providers.dart ──
 
-// Repository（直接注入 ApiClient + 回调组合多个 SDK 能力）
+// Repository（注入 Facade 接口 + 回调组合多个 SDK 能力）
 final authRepositoryProvider = Provider<AuthRepository>((ref) {
   final apiConfig = ref.read(apiConfigProvider);
   return AuthRepositoryImpl(
-    client: ref.read(apiClientProvider),          // 直接注入 ApiClient
+    client: ref.read(networkSdkApiProvider),       // 注入 Facade 接口
     onTokenUpdate: (token) {
       apiConfig.updateToken(token);               // 内存（networks_sdk）
       // secureStorage.saveToken(token);          // 持久化（storage_sdk，待接入）
@@ -6199,7 +6214,7 @@ import '../../../domain/repositories/message_repository.dart';
 // ── Repository ──
 final messageRepositoryProvider = Provider<MessageRepository>((ref) {
   return MessageRepositoryImpl(
-    client: ref.read(apiClientProvider),       // 直接注入 ApiClient
+    client: ref.read(networkSdkApiProvider),    // 注入 Facade 接口
   );
 });
 
@@ -6207,7 +6222,7 @@ final messageRepositoryProvider = Provider<MessageRepository>((ref) {
 // 如需 UseCase（多步编排、跨模块协调），参考 auth_providers.dart 中的 loginUseCaseProvider。
 
    
 
-
    原则：app/di/ 只放 SDK 基础设施（ApiConfig / ApiClient），业务模块的 DI 链路（Repository → UseCase 按需）内聚在 features/{模块}/di/{模块}_providers.dart 中。
    
+
    原则：app/di/ 只放 SDK 基础设施（ApiConfig / NetworksSdkApi），业务模块的 DI 链路（Repository → UseCase 按需）内聚在 features/{模块}/di/{模块}_providers.dart 中。
    
 
 
 
    3.2 编写 ViewModel
    
@@ -6280,7 +6295,7 @@ class LoginViewModel extends _$LoginViewModel {
   → View: vm.doSomething(...)
     → ViewModel: ref.read(xxxRepositoryProvider).doSomething(...)
       → RepositoryImpl.doSomething()                               // data/repositories/
-        → _client.executeRequest(XxxRequest)                       // 直接调 ApiClient
+        → _client.executeRequest(XxxRequest)                       // 调 NetworksSdkApi
           → 自动注入 header → HTTP 请求 → 自动解码 → DTO
         → dto.toEntity() → Domain Entity
     ← state = state.copyWith(...)                                  // 更新状态
@@ -6295,8 +6310,8 @@ class LoginViewModel extends _$LoginViewModel {
       → LoginUseCase: 格式校验（邮箱 + 密码）                      // features/auth/usecases/
       → LoginUseCase: authRepository.login(...)
         → AuthRepositoryImpl.login()                               // data/repositories/
-          → _client.executeRequest(LoginRequest)                   // 直接调 ApiClient
-            → AuthInterceptor → Dio.request → RetryInterceptor   // 自动处理
+          → _client.executeRequest(LoginRequest)                   // 调 NetworksSdkApi
+            → Auth → Encryption → Dio.request → Retry → Logging // 拦截器链自动处理
           ← request.decodeResponse → LoginData.fromJson           // 自动解码
         ← LoginData（DTO）
         → onTokenUpdate(token)                                    // 回调：内存写入 + 持久化
@@ -6360,7 +6375,7 @@ class SendMessageRequest extends ApiRequestable<SendMessageData>
 }
 
    
 
-
    保存 → 自动生成 → 然后在 Repository 中直接调 ApiClient 就完了：
    
+
    保存 → 自动生成 → 然后在 Repository 中调 NetworksSdkApi 就完了：
    
 
 
    // 在 MessageRepositoryImpl 中添加
 Future<SendMessageData?> sendMessage({
@@ -6568,18 +6583,18 @@ final apiConfigProvider = Provider<ApiConfig>((ref) {
   );
 });
 
-/// API 客户端 Provider（全局单例）
-/// 内部自动挂载 AuthInterceptor / RetryInterceptor / LoggingInterceptor
-final apiClientProvider = Provider<ApiClient>((ref) {
+/// Networks SDK API Provider（全局单例，Facade 接口）
+/// 内部自动挂载 AuthInterceptor / EncryptionInterceptor / RetryInterceptor / LoggingInterceptor
+final networkSdkApiProvider = Provider<NetworksSdkApi>((ref) {
   final config = ref.read(apiConfigProvider);
-  return ApiClient(config: config);
+  return NetworksSdkWiring.build(config: config);
 });
 
    
 
 
    DI 装配总览
    
 
 
    app/di/                                ← 手动装配：SDK 基础设施
-└── network_provider.dart              → apiConfigProvider + apiClientProvider
+└── network_provider.dart              → apiConfigProvider + networkSdkApiProvider
 
 features/{模块}/di/                    ← 手动装配：业务模块 DI 链路（Repository → UseCase 按需）
 ├── auth/di/auth_providers.dart        → authRepositoryProvider
@@ -6593,7 +6608,7 @@ features/{模块}/presentation/          ← @riverpod 自动生成：ViewModel
 
    
 
 
    di/ 目录的定位：只放需要手动装配的 Provider（构造注入、回调组合等）。ViewModel Provider 由 @riverpod 注解自动生成（写在 presentation/ 下），不在 di/ 中。
    
-
    最小化原则：app/di/ 只提供 SDK 能力（ApiConfig / ApiClient），不放业务模块的 Provider。每个业务模块的手动装配 Provider 内聚在 features/{模块}/di/{模块}_providers.dart 中，需要时才创建。
    
+
    最小化原则：app/di/ 只提供 SDK 能力（ApiConfig / NetworksSdkApi），不放业务模块的 Provider。每个业务模块的手动装配 Provider 内聚在 features/{模块}/di/{模块}_providers.dart 中，需要时才创建。
    
 
 
    SDK 间解耦：回调注入模式
    
 
@@ -6605,7 +6620,7 @@ final authRepositoryProvider = Provider<AuthRepository>((ref) {
   // final secureStorage = ref.read(secureStorageProvider);  // storage_sdk（待接入）
 
   return AuthRepositoryImpl(
-    client: ref.read(apiClientProvider),          // 直接注入 ApiClient
+    client: ref.read(networkSdkApiProvider),       // 注入 Facade 接口
     onTokenUpdate: (token) {
       apiConfig.updateToken(token);               // 内存（networks_sdk）
       // secureStorage.saveToken(token);          // 持久化（storage_sdk，待接入）
@@ -6635,6 +6650,7 @@ final authRepositoryProvider = Provider<AuthRepository>((ref) {
     networkError: (msg)    => showToast('网络错误: $msg'),
     decodingError: (msg)   => showToast('数据解析失败'),
     apiError: (code, msg)  => showToast('服务端错误[$code]: $msg'),
+    cancelled: ()          => {}, // 用户主动取消，通常不提示
     unknown: (msg)         => showToast('未知错误'),
   );
 }
@@ -7137,9 +7153,9 @@ abstract class ProfileRepository {
 
 
    // data/repositories/profile_repository_impl.dart
 class ProfileRepositoryImpl implements ProfileRepository {
-  final ApiClient _client;
+  final NetworksSdkApi _client;
 
-  ProfileRepositoryImpl({required ApiClient client})
+  ProfileRepositoryImpl({required NetworksSdkApi client})
       : _client = client;
 
   @override
@@ -7166,7 +7182,7 @@ import '../../../app/di/network_provider.dart';
 // ── Repository ──
 final profileRepositoryProvider = Provider<ProfileRepository>((ref) {
   return ProfileRepositoryImpl(
-    client: ref.read(apiClientProvider),       // 直接注入 ApiClient
+    client: ref.read(networkSdkApiProvider),    // 注入 Facade 接口
   );
 });
 
@@ -7174,7 +7190,7 @@ final profileRepositoryProvider = Provider<ProfileRepository>((ref) {
 // ViewModel 通过 @riverpod 注解自动生成 Provider，无需额外注册。
 
    
 
-
    说明：Profile 属于简单模板，ViewModel 直接调 Repository，无需 UseCase 中间层。app/di/ 只提供 SDK 基础设施（ApiConfig / ApiClient），业务模块的 DI 链路内聚在 Feature 目录下。
    
+
    说明：Profile 属于简单模板，ViewModel 直接调 Repository，无需 UseCase 中间层。app/di/ 只提供 SDK 基础设施（ApiConfig / NetworksSdkApi），业务模块的 DI 链路内聚在 Feature 目录下。
    
 
 
    Feature 结构图示
    
 
@@ -7714,7 +7730,7 @@ sequenceDiagram
     participant Repo as domain/repositories/
    message_repository.dart
     participant RepoImpl as data/repositories/
    message_repository_impl.dart
     participant LocalDS as data/local/
    message_local_ds.dart
-    participant SDK as networks_sdk/
    ApiClient / SocketClient
+    participant SDK as networks_sdk/
    NetworksSdkApi / SocketClient
     participant WS as WebSocket Server
 
     UI->>VM: 1. 用户点击发送按钮
@@ -7746,7 +7762,7 @@ sequenceDiagram
 
  • Repository 接口：UseCase 通过 domain/repositories/message_repository.dart 接口调用
    • 
 
  • Repository 实现：data/repositories/message_repository_impl.dart 实现具体逻辑
    • 
 
  • 本地优先：先保存到 data/local/message_local_ds.dart
    • 
-
  • 网络发送：Repository 直接调 SDK（ApiClient / SocketClient）发送
    • 
+
  • 网络发送：Repository 调 SDK（NetworksSdkApi / SocketClient）发送
    • 
 
  • 服务器确认：WebSocket 服务器确认接收
    • 
 
  • 状态更新：更新本地数据库中的消息状态
    • 
 
  • 数据返回：层层返回，最终更新 UI
    • 
@@ -7830,7 +7846,7 @@ abstract class MessageRepository {
 
    // data/repositories/message_repository_impl.dart
 class MessageRepositoryImpl implements MessageRepository {
   final MessageLocalDataSource _localDS;
-  final ApiClient _client;           // 直接注入 ApiClient / SocketClient
+  final NetworksSdkApi _client;      // 注入 Facade 接口
 
   MessageRepositoryImpl(this._localDS, this._client);
 
@@ -7861,7 +7877,7 @@ class MessageRepositoryImpl implements MessageRepository {
 MessageRepository messageRepository(MessageRepositoryRef ref) {
   return MessageRepositoryImpl(
     ref.watch(messageLocalDataSourceProvider),
-    ref.watch(apiClientProvider),        // 直接注入 ApiClient
+    ref.watch(networkSdkApiProvider),     // 注入 Facade 接口
   );
 }
 
    
@@ -7895,7 +7911,7 @@ sequenceDiagram
     participant RepoImpl as data/repositories/
    chat_repository_impl.dart
     participant Cache as data/cache/
    cache_manager.dart
     participant LocalDS as data/local/
    chat_local_ds.dart
-    participant SDK as networks_sdk/
    ApiClient
+    participant SDK as networks_sdk/
    NetworksSdkApi
 
     UI->>VM: 1. 页面初始化
     VM->>UC: 2. 调用 LoadChatListUseCase
@@ -7907,7 +7923,7 @@ sequenceDiagram
     else 缓存未命中
         RepoImpl->>LocalDS: 6b. 读取本地数据库
         LocalDS-->>RepoImpl: 7. 返回本地数据
-        RepoImpl->>SDK: 8. 直接调 ApiClient 请求远程数据
+        RepoImpl->>SDK: 8. 调 NetworksSdkApi 请求远程数据
         SDK-->>RepoImpl: 9. 返回最新数据
         RepoImpl->>LocalDS: 10. 更新本地数据库
         RepoImpl->>Cache: 11. 更新缓存
@@ -8583,9 +8599,9 @@ abstract class ChatRepository {
   Future<void> sendMessage(Message message);
 }
 
-// 2. Repository 实现层（直接注入 ApiClient）
+// 2. Repository 实现层（注入 Facade 接口）
 class ChatRepositoryImpl implements ChatRepository {
-  final ApiClient client;
+  final NetworksSdkApi client;
   final LocalDataSource localDataSource;
   final MessageMapper mapper;
 
@@ -8603,7 +8619,7 @@ class ChatRepositoryImpl implements ChatRepository {
       return localDTOs.map(mapper.toEntity).toList();
     }
 
-    // 直接调 ApiClient 从远程获取
+    // 调 NetworksSdkApi 从远程获取
     final response = await client.executeRequest(
       GetMessagesRequest(chatId: chatId),
     );
@@ -9770,6 +9786,146 @@ flowchart TD
 
    单一职责：每个模块只做一件事，UseCase/ViewModel/Repository 各司其职
    
 
 
+
+
+
    第八部分：UI 设计规范
    
+
+
    本章定义颜色、字体、组件、弹框、图标的命名与使用规则，明确设计与研发的协作约定。Figma 按此命名，代码按此封装，两端名称一一对应。
    
+
+
    8.0 核心约定
    
+
+
    
+
    全局只有一份
    
+
    颜色、字体、基础组件、业务弹框、图片、图标——Figma 里每种元素只有一个定义。没有"备用版本"，没有"临时副本"，不允许两个"差不多一样"的组件并存。
    
+
    
+
+
      
+
    1. Figma 命名是重中之重：点中任何元素都必须看到抽象名称。六类无例外：
+  
        
+  
      • 颜色 — 如 primary、surface
        • 
+  
      • 字体 — 如 Body/Medium、Label/Small
        • 
+  
      • 基础组件 — 如 Button/Primary、Input/Default，全局只有一个版本
        • 
+  
      • 业务弹框 — 如 Dialog/Confirm
        • 
+  
      • 图片 — Figma 统一导出，代码侧 AppAssets 注册，不硬编码路径
        • 
+  
      • 图标 — 如 send、more_options，代码侧 AppIcons 调用
        • 
+  
      
+
      2. 
+
    2. 基础组件定稿后不随意改动：需改动时必须先告知研发，评估影响范围，双方同步后再执行
      3. 
+
    3. UI 团队自主维护 UI 基建体系：研发照着 Figma 名字封装，名称必须完全一致
      4. 
+
    4. 所有元素遵循同一套命名规则：新增任何元素先在 Figma 定名，研发用相同名字注册
      5. 
+
    
+
+
    
+图片和组件是重灾区：没有统一来源时，不同研发各自导出同一张图，文件名不同、尺寸不同，最终项目里堆满重复文件。Figma 统一命名、代码统一注册，才能从源头堵住。
+
    
+
+
    8.1 颜色体系
    
+
+
    所有颜色通过抽象名称引用。抽象名在亮色 / 暗色两套主题下对应不同色值，修改主题只需改映射表，不需逐个找组件。
    
+
+
    语义色（随主题变化）
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    抽象名Figma 名亮色暗色用途
    primaryPrimary#2F80ED#5BA3F5主操作、链接、选中态
    backgroundBackground#F8F9FA#202124页面底色
    surfaceSurface#FFFFFF#3C4043卡片、弹框、输入框
    onSurfaceOn Surface#202124#FFFFFFsurface 上的文字
    errorError#EB5757错误状态
    successSuccess#27AE60成功状态
    warningWarning#F2C94C警告状态
    
+
+
    灰阶（固定值，不随主题变化）
    
+
+
+
+
+
+
+
+
+
    名称色值名称色值名称色值
    white#FFFFFFgray50#F8F9FAgray100#F1F3F4
    gray200#E8EAEDgray400#BDC1C6gray600#80868B
    gray800#3C4043gray900#202124black#000000
    
+
+
    使用原则：需随主题切换 → 用语义色（primary、surface）；亮暗保持不变 → 用灰阶固定值。
    
+
+
    8.2 字体体系
    
+
+
    字体按层级分五档：Display、Headline、Title、Body、Label，每档三个尺寸。Figma 中按 层级/尺寸 格式命名（如 Body/Large），开发用同名变量调用。
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    Figma 名称字号字重行高字距典型用途
    DISPLAY
    Display/Large5740064-0.25启动页大标题、空状态
    Display/Medium4540052——
    Display/Small3640044——
    HEADLINE
    Headline/Large3240040—页面主标题、导航栏
    Headline/Medium2840036——
    Headline/Small2440032——
    TITLE
    Title/Large2250028—会话列表名称、设置项标题
    Title/Medium16500240.15卡片标题、列表主行
    Title/Small14500200.1—
    BODY
    Body/Large16400240.5聊天气泡、表单输入
    Body/Medium14400200.25正文说明、列表副行
    Body/Small12400160.4辅助信息、提示文字
    LABEL
    Label/Large14500200.1按钮文字、Tab 标签、Badge
    Label/Medium12500160.5次要标签、徽标文字
    Label/Small11500160.5最小粒度标签
    语义样式
    Section Label13600—0.5列表分组标题、设置分区
    Body/Muted1240016—说明文字（灰色，低对比度）
    Body/Error1240016—表单错误提示（红色）
    Label/Muted1250016—时间戳、元数据（低对比度）
    
+
+
    8.3 组件 — Button
    
+
+
    按钮共四种变体，每种有明确使用场景和 Figma 组件名。每个页面上主操作只用一个 Primary。
    
+
+
+
+
+
+
+
+
+
+
    Figma 组件名用途亮色样式暗色样式状态
    Button/Primary主操作（登录、发送、确认），每屏最多一次背景 #2F80ED，白字背景 #5BA3F5，白字默认 / Loading / 禁用（#BDC1C6）
    Button/Secondary次要操作（注册、稍后再说），描边样式描边 #2F80ED，蓝字描边 #5BA3F5，蓝字默认 / 禁用
    Button/Text辅助链接（忘记密码、查看全部、弹框取消）无背景，蓝字无背景，蓝字默认
    Button/Inverse反色按钮（深色背景高亮），支持左侧图标背景 #202124，白字背景 #FFFFFF，黑字默认
    
+
+
    8.4 业务弹框 — Dialog
    
+
+
    当前封装一种通用确认弹框 Dialog/Confirm，后续新增先在 Figma 以 Dialog/ 前缀命名。
    
+
+
+
+
+
+
+
+
+
    项目说明
    结构标题（不超 15 字） + 内容 + 操作区（取消 Text 样式 | 确认 Primary 样式）
    可配置标题文字、内容文字、确认/取消标签、点击背景是否可关闭
    返回值确认 / 取消 / 关闭（点击背景）
    
+
+
    8.5 图标规范
    
+
+
      
+
    1. UI 先命名，开发跟随：Figma 确定名称，开发用完全相同的名称封装到 AppIcons
      2. 
+
    2. 名称有实际语义：全小写下划线，如 send、add_contact、more_options。不用拼音，不缩写
      3. 
+
    3. 统一用 AppIcons 调用：不允许直接用裸 icon 库变量，替换时改一处全局生效
      4. 
+
    4. 同义图标只保留一个：同功能图标在整个产品内只存在一种
      5. 
+
    
+
+
    新增图标流程：设计师 Figma 确认名称 → 告知开发 → 开发用相同名称在 AppIcons 注册。两端名称必须完全一致。
    
+
 
     
 
diff --git a/apps/im_app/android/settings.gradle.kts b/apps/im_app/android/settings.gradle.kts
index ca7fe06..3ca60d7 100644
--- a/apps/im_app/android/settings.gradle.kts
+++ b/apps/im_app/android/settings.gradle.kts
@@ -21,6 +21,7 @@ plugins {
     id("dev.flutter.flutter-plugin-loader") version "1.0.0"
     id("com.android.application") version "8.11.1" apply false
     id("org.jetbrains.kotlin.android") version "2.2.20" apply false
+    id("org.jetbrains.kotlin.plugin.compose") version "2.2.20" apply false
 }
 
 include(":app")
diff --git a/apps/im_app/ios/Podfile b/apps/im_app/ios/Podfile
index cf9087f..9100f59 100644
--- a/apps/im_app/ios/Podfile
+++ b/apps/im_app/ios/Podfile
@@ -38,5 +38,10 @@ end
 post_install do |installer|
   installer.pods_project.targets.each do |target|
     flutter_additional_ios_build_settings(target)
+    target.build_configurations.each do |config|
+      # 对没有在 podspec 里声明 swift_version 的 pod 设置兜底版本。
+      # 已有 swift_version 的 pod（含第三方如 Agora）CocoaPods 优先使用其 podspec 值，不受影响。
+      config.build_settings['SWIFT_VERSION'] ||= '6.2'
+    end
   end
 end
diff --git a/apps/im_app/ios/Runner.xcodeproj/project.pbxproj b/apps/im_app/ios/Runner.xcodeproj/project.pbxproj
index 2bf7cf1..e2932a4 100644
--- a/apps/im_app/ios/Runner.xcodeproj/project.pbxproj
+++ b/apps/im_app/ios/Runner.xcodeproj/project.pbxproj
@@ -164,7 +164,6 @@
 				1C416905D0EA345032C4E612 /* Pods-RunnerTests.release.xcconfig */,
 				9538107A41BCB5B5D84FBAF3 /* Pods-RunnerTests.profile.xcconfig */,
 			);
-			name = Pods;
 			path = Pods;
 			sourceTree = "";
 		};
@@ -489,7 +488,7 @@
 				SUPPORTS_MAC_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SUPPORTS_XR_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SWIFT_OBJC_BRIDGING_HEADER = "Runner/Runner-Bridging-Header.h";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.0;
 				TARGETED_DEVICE_FAMILY = 1;
 				VERSIONING_SYSTEM = "apple-generic";
 			};
@@ -508,7 +507,7 @@
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Runner.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Runner";
 			};
 			name = Debug;
@@ -524,7 +523,7 @@
 				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = com.cusotmer.im.imApp.RunnerTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Runner.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Runner";
 			};
 			name = Release;
@@ -540,7 +539,7 @@
 				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = com.cusotmer.im.imApp.RunnerTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/Runner.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/Runner";
 			};
 			name = Profile;
@@ -678,7 +677,7 @@
 				SUPPORTS_XR_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SWIFT_OBJC_BRIDGING_HEADER = "Runner/Runner-Bridging-Header.h";
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.0;
 				TARGETED_DEVICE_FAMILY = 1;
 				VERSIONING_SYSTEM = "apple-generic";
 			};
@@ -705,7 +704,7 @@
 				SUPPORTS_MAC_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SUPPORTS_XR_DESIGNED_FOR_IPHONE_IPAD = NO;
 				SWIFT_OBJC_BRIDGING_HEADER = "Runner/Runner-Bridging-Header.h";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.0;
 				TARGETED_DEVICE_FAMILY = 1;
 				VERSIONING_SYSTEM = "apple-generic";
 			};
diff --git a/apps/im_app/ios/Runner/AppDelegate.swift b/apps/im_app/ios/Runner/AppDelegate.swift
index fe8e3fa..8d8a0bd 100644
--- a/apps/im_app/ios/Runner/AppDelegate.swift
+++ b/apps/im_app/ios/Runner/AppDelegate.swift
@@ -1,8 +1,8 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 @main
-@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
+@objc class AppDelegate: FlutterAppDelegate {
 
   override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     return super.application(application, didFinishLaunchingWithOptions: launchOptions)
@@ -16,9 +16,11 @@ import UIKit
     sceneConfig.delegateClass = SceneDelegate.self
     return sceneConfig
   }
+}
 
-  // MARK: - FlutterImplicitEngineDelegate
-
+// FlutterImplicitEngineDelegate 来自 Flutter ObjC 框架，尚未标注 @MainActor，
+// 用 @preconcurrency 抑制 Swift 6 ConformanceIsolation 错误。
+extension AppDelegate: @preconcurrency FlutterImplicitEngineDelegate {
   func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
     GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
   }
diff --git a/apps/im_app/lib/app/di/network_provider.dart b/apps/im_app/lib/app/di/network_provider.dart
index e1792c1..92f485c 100644
--- a/apps/im_app/lib/app/di/network_provider.dart
+++ b/apps/im_app/lib/app/di/network_provider.dart
@@ -6,6 +6,8 @@ import 'package:networks_sdk/networks_sdk.dart';
 import '../../core/foundation/api_paths.dart';
 import '../../core/foundation/config.dart';
 import '../../core/foundation/constants.dart';
+import '../../core/foundation/errors.dart';
+import '../../core/foundation/utils.dart';
 import '../../core/services/network_monitor.dart';
 import '../../core/services/socket_manager.dart';
 
@@ -47,6 +49,21 @@ final networkMonitorProvider = Provider((ref) {
   return monitor;
 });
 
+// ── Token 更新事件流 ─────────────────────────────────────────────────────────
+
+/// Token 更新事件流
+///
+/// apiConfigProvider.onTokenUpdated → 推送新 token 到此流
+/// socketManagerProvider → 监听此流 → 同步 token 到 WebSocket
+/// onBeforeReconnect 中刷新 token 后调用 apiConfig.updateToken → tokenStream.add，
+/// 需要同步传播到 socketManager.updateToken → socketClient._currentToken，
+/// 确保随后的 _doConnect() 使用新 token。异步模式下 _doConnect 会在 stream
+final _tokenUpdateStreamProvider = Provider>((ref) {
+  final controller = StreamController.broadcast(sync: true);
+  ref.onDispose(controller.close);
+  return controller;
+});
+
 // ── HTTP 基础设施 ─────────────────────────────────────────────────────────────
 
 /// API 配置 Provider（全局单例）
@@ -58,15 +75,18 @@ final networkMonitorProvider = Provider((ref) {
 /// 请求前先判断网络状态，无网络时直接抛 [ApiError.noNetworkConnection]。
 final apiConfigProvider = Provider((ref) {
   final networkMonitor = ref.read(networkMonitorProvider);
+  final tokenStream = ref.read(_tokenUpdateStreamProvider);
 
   return ApiConfig(
     baseURL: AppConfig.apiBaseUrl,
     platformHeaders: {
-      'Platform': 'Android', // TODO: 运行时从平台 API 获取
+      'Platform': 'Android', // TODO: 运行时从 platform API 获取
       'client-version': '1.0.0', // TODO: 运行时从 package_info 获取
+      'Channel': '', // TODO: 从 AppConfig 读取渠道标识
+      'lang': 'zh-CN', // TODO: 从 l10n_sdk 或系统 locale 动态获取
     },
-    tokenExpiredCodes: {30002, 30003, 30124},
-    forceLogoutCodes: {30125},
+    tokenExpiredCodes: ApiErrorCodes.tokenExpiredCodes,
+    forceLogoutCodes: ApiErrorCodes.forceLogoutCodes,
     onForceLogout: () {
       // TODO: 清除登录态，跳转登录页
     },
@@ -74,7 +94,17 @@ final apiConfigProvider = Provider((ref) {
       // TODO: App 层刷新 token 逻辑
       return null;
     },
+    onTokenUpdated: (newToken) {
+      // 通过事件流同步到 WebSocket，避免直接引用 socketManagerProvider 造成循环依赖
+      tokenStream.add(newToken);
+    },
     onCheckNetworkAvailable: () async => networkMonitor.isConnected,
+    onEncryptRequest: null, // TODO: 接入 cipher_guard_sdk 后注入请求加密回调
+    onDecryptResponse: null, // TODO: 接入 cipher_guard_sdk 后注入响应解密回调
+    onBusinessError: null, // TODO: 接入业务错误统一处理（弹窗 / Toast / 跳转等）
+    onTransformResponse:
+        null, // TODO: 如后端信封结构非标准，在此归一化为 { code, data, message }
+    onGetTokenExpiry: parseJwtExpiry,
     maxRetries: AppConstants.maxRetries,
     retryBaseDelay: AppConstants.retryBaseDelay,
     onLog: (message, {tag}) {
@@ -94,16 +124,47 @@ final networkSdkApiProvider = Provider((ref) {
 
 // ── WebSocket 基础设施 ────────────────────────────────────────────────────────
 
-/// SocketConfig Provider（全局单例）
+/// SocketConfig Provider（内部使用，不对外暴露）
 ///
 /// 与 apiConfigProvider 对称，通过回调注入 App 层能力，
 /// SDK 内部不调用其他 SDK。
-final socketConfigProvider = Provider((ref) {
+final _socketConfigProvider = Provider((ref) {
   final networkMonitor = ref.read(networkMonitorProvider);
 
   return SocketConfig(
     maxReconnectAttempts: AppConstants.maxRetries,
     maxReconnectDelay: AppConstants.maxReconnectDelay,
+    unlimitedReconnect: true, // IM 场景始终保持连接
+    onBuildConnectUrl:
+        null, // TODO: 接入 cipher_guard_sdk 后注入 WS URL 加密（路径/token/cipher 参数）
+    onEncryptMessage: null, // TODO: 接入 cipher_guard_sdk 后注入消息加密回调
+    onDecryptMessage: null, // TODO: 接入 cipher_guard_sdk 后注入消息解密回调
+    onBeforeReconnect: () async {
+      // SocketClient 内部重连（心跳超时、stream onDone）前调用。
+      // 与 SocketManager.onBeforeReconnect 职责相同：检查 token 并按需刷新。
+      // 刷新后通过 sync stream 同步传播到 SocketClient._currentToken，
+      // 确保随后的 _doConnect() 使用新 token。
+      final apiConfig = ref.read(apiConfigProvider);
+      final currentToken = apiConfig.token;
+      if (currentToken == null || apiConfig.onGetTokenExpiry == null) return;
+
+      final expiry = apiConfig.onGetTokenExpiry!(currentToken);
+      if (expiry == null) return;
+
+      final remaining = expiry.difference(DateTime.now());
+      if (remaining > apiConfig.proactiveRefreshThreshold) return;
+
+      // ignore: avoid_print
+      print(
+        '[Socket] Token expiring in ${remaining.inMinutes}min, refreshing before reconnect',
+      );
+      final newToken = await apiConfig.onTokenRefresh?.call();
+      if (newToken != null && newToken.isNotEmpty) {
+        // updateToken → onTokenUpdated → sync stream → manager.updateToken
+        // → _client.updateToken → socketClient._currentToken 同步更新
+        apiConfig.updateToken(newToken);
+      }
+    },
     onLog: (message, {tag}) {
       // ignore: avoid_print
       print('[${tag ?? 'Socket'}] $message');
@@ -114,12 +175,11 @@ final socketConfigProvider = Provider((ref) {
   );
 });
 
-/// SocketClient Provider（全局单例）
+/// SocketClient Provider（内部使用，不对外暴露）
 ///
-/// 与 apiClientProvider 对称。
-final socketClientProvider = Provider((ref)
-{
-  final config = ref.read(socketConfigProvider);
+/// 与 networkSdkApiProvider 对称。
+final _socketClientProvider = Provider((ref) {
+  final config = ref.read(_socketConfigProvider);
   return NetworksMessagingApi()..initialize(config);
 });
 
@@ -139,17 +199,43 @@ final socketClientProvider = Provider((ref)
 /// 网络状态变化由 [networkMonitorProvider]（公共服务）驱动，
 /// 自动触发断连/重连。
 ///
+/// Token 更新由 [_tokenUpdateStreamProvider] 事件流驱动，
+/// HTTP 层刷新 token 后自动同步到 WebSocket。
+///
 /// onMessageTransform 参考 HTTP 层 onTokenRefresh 的回调模式：
 /// 后续接入加解密 SDK 时，在此注入解密回调，
 /// SDK 内部不调用其他 SDK。
 final socketManagerProvider = Provider((ref) {
-  final client = ref.read(socketClientProvider);
+  final client = ref.read(_socketClientProvider);
   final networkMonitor = ref.read(networkMonitorProvider);
+  final apiConfig = ref.read(apiConfigProvider);
+  final tokenStream = ref.read(_tokenUpdateStreamProvider);
 
   final manager = SocketManager(
     client: client,
     wsUrl: _buildWsUrl(AppConfig.apiBaseUrl),
     onMessageTransform: null, // TODO: 接入加解密 SDK 后注入解密回调
+    onBeforeReconnect: () async {
+      // 重连前检查 token 是否即将过期，是则主动刷新
+      final currentToken = apiConfig.token;
+      if (currentToken == null || apiConfig.onGetTokenExpiry == null) return;
+
+      final expiry = apiConfig.onGetTokenExpiry!(currentToken);
+      if (expiry == null) return;
+
+      final remaining = expiry.difference(DateTime.now());
+      if (remaining > apiConfig.proactiveRefreshThreshold) return;
+
+      // ignore: avoid_print
+      print(
+        '[SocketManager] Token expiring in ${remaining.inMinutes}min, refreshing before reconnect',
+      );
+      final newToken = await apiConfig.onTokenRefresh?.call();
+      if (newToken != null && newToken.isNotEmpty) {
+        // updateToken 触发 onTokenUpdated → tokenStream → socketManager.updateToken
+        apiConfig.updateToken(newToken);
+      }
+    },
     onCheckNetworkAvailable: () async => networkMonitor.isConnected,
     onLog: (message, {tag}) {
       // ignore: avoid_print
@@ -157,13 +243,19 @@ final socketManagerProvider = Provider((ref) {
     },
   );
 
+  // 监听 token 更新事件 → 同步到 WebSocket
+  final tokenSub = tokenStream.stream.listen((newToken) {
+    manager.updateToken(newToken);
+  });
+
   // 监听网络状态变化 → 驱动 SocketManager 断连/重连
-  final subscription = networkMonitor.onStatusChanged.listen((isAvailable) {
+  final networkSub = networkMonitor.onStatusChanged.listen((isAvailable) {
     manager.handleNetworkStatusChanged(isAvailable: isAvailable);
   });
 
   ref.onDispose(() {
-    subscription.cancel();
+    tokenSub.cancel();
+    networkSub.cancel();
     unawaited(manager.dispose());
   });
 
@@ -215,23 +307,55 @@ String _buildWsUrl(String httpBaseUrl) {
 //  Provider 链路：
 //
 //    networkMonitorProvider（公共服务，HTTP + WS 共用）
-//      ├── apiConfigProvider → apiClientProvider         ← HTTP 层
-//      └── socketConfigProvider → socketClientProvider   ← WS 层
+//      ├── apiConfigProvider → networkSdkApiProvider      ← HTTP 层
+//      └── _socketConfigProvider → _socketClientProvider   ← WS 层（内部）
 //            → socketManagerProvider
 //
+//    _tokenUpdateStreamProvider（打破循环引用的中间层）
+//      ← apiConfigProvider.onTokenUpdated 推送
+//      → socketManagerProvider 监听 → socketManager.updateToken()
+//
 //  网络事件驱动链路：
 //
 //    connectivity_plus（平台网络事件）
 //      → NetworkMonitor.onStatusChanged（true / false）
 //        → SocketManager.handleNetworkStatusChanged()
 //          → 断网: disconnect()
-//          → 恢复: connect(token: lastToken)
+//          → 恢复: onBeforeReconnect → connect(token: lastToken)
 //
 //  前后台事件驱动链路：
 //
 //    WidgetsBindingObserver（App 层 app.dart）
-//      → SocketManager.onEnterBackground() → disconnect
-//      → SocketManager.onEnterForeground() → reconnect
+//      → SocketManager.onEnterBackground()
+//          disconnectInBackground=true  → disconnect（默认，移动端省电）
+//          disconnectInBackground=false → 完全保活，不断连不暂停心跳（桌面端）
+//      → SocketManager.onEnterForeground() → onBeforeReconnect → reconnect
+//
+//  Token 刷新 → WebSocket 同步链路：
+//
+//    RetryInterceptor 检测 token 过期
+//      → TokenRefreshManager.refreshIfNeeded()
+//      → apiConfig.updateToken(newToken)
+//      → onTokenUpdated(newToken)
+//      → _tokenUpdateStream.add(newToken)
+//      → socketManager.updateToken(newToken)  // 不断连，下次重连自动用新 token
+//
+//  主动 token 刷新（重连前，两个层级）：
+//
+//    SocketManager 层（前台恢复 / 网络恢复触发）：
+//      SocketManager.onBeforeReconnect()
+//        → 解析 JWT exp → 距过期 < 阈值
+//        → apiConfig.onTokenRefresh() → 刷新
+//        → apiConfig.updateToken(newToken)
+//        → sync stream → manager.updateToken → _lastToken 更新
+//        → _client.connect(token: _lastToken) 使用新 token
+//
+//    SocketClient 层（心跳超时 / stream onDone 触发）：
+//      SocketConfig.onBeforeReconnect()
+//        → 同上逻辑：检查 JWT exp → 刷新 → apiConfig.updateToken
+//        → sync stream → manager.updateToken → _client.updateToken
+//        → socketClient._currentToken 同步更新
+//        → _doConnect() 使用新 token
 //
 //  Repository 直接注入 ApiClient，通过回调注入其他 SDK 能力：
 //
@@ -313,7 +437,7 @@ String _buildWsUrl(String httpBaseUrl) {
 //   final authRepositoryProvider = Provider((ref) {
 //     final apiConfig = ref.read(apiConfigProvider);
 //     return AuthRepositoryImpl(
-//       client: ref.read(apiClientProvider),       // 直接注入
+//       client: ref.read(networkSdkApiProvider),    // 注入 Facade 接口
 //       onTokenUpdate: (token) {
 //         apiConfig.updateToken(token);             // 内存（network_sdk）
 //         // secureStorage.saveToken(token);        // 持久化（crypto_sdk）
diff --git a/apps/im_app/lib/core/foundation/errors.dart b/apps/im_app/lib/core/foundation/errors.dart
index e69de29..983c096 100644
--- a/apps/im_app/lib/core/foundation/errors.dart
+++ b/apps/im_app/lib/core/foundation/errors.dart
@@ -0,0 +1,57 @@
+/// API 错误码常量
+///
+/// 集中管理后端业务错误码，避免散落在各处硬编码。
+/// 按业务域分组，命名风格对齐后端定义。
+///
+/// 使用方式：
+/// ```dart
+/// ApiConfig(
+///   tokenExpiredCodes: ApiErrorCodes.tokenExpiredCodes,
+///   forceLogoutCodes: ApiErrorCodes.forceLogoutCodes,
+/// )
+/// ```
+class ApiErrorCodes {
+  ApiErrorCodes._();
+
+  // ── 认证（30001-30009）──
+
+  /// Token 无效
+  static const int tokenInvalid = 30002;
+
+  /// JWT 无效
+  static const int jwtInvalid = 30003;
+
+  /// 签名方法错误
+  static const int signingMethodError = 30008;
+
+  /// 密钥解析失败
+  static const int parsingKeyError = 30009;
+
+  /// Session 无效
+  static const int sessionInvalid = 30124;
+
+  /// Refresh Token 失效
+  static const int refreshTokenFailed = 30125;
+
+  /// 账号在其他设备登录
+  static const int loggedInAnotherDevice = 30006;
+
+  // ── 错误码集合 ──
+
+  /// Token 过期错误码集合 — 触发自动刷新 Token
+  static const Set tokenExpiredCodes = {
+    tokenInvalid,
+    jwtInvalid,
+    sessionInvalid,
+  };
+
+  /// 强制登出错误码集合 — 触发退出登录流程
+  static const Set forceLogoutCodes = {refreshTokenFailed};
+
+  /// 踢下线错误码集合 — 触发踢下线 UI 提示
+  static const Set kickOffCodes = {
+    loggedInAnotherDevice,
+    signingMethodError,
+    parsingKeyError,
+  };
+}
diff --git a/apps/im_app/lib/core/foundation/utils.dart b/apps/im_app/lib/core/foundation/utils.dart
index e69de29..707912c 100644
--- a/apps/im_app/lib/core/foundation/utils.dart
+++ b/apps/im_app/lib/core/foundation/utils.dart
@@ -0,0 +1,32 @@
+import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
+
+/// JWT token 过期时间解析
+///
+/// 使用 dart_jsonwebtoken 解码 JWT payload，提取 `exp` claim 返回过期时间。
+/// 返回 null 表示无法解析（非 JWT 格式或缺少 exp 字段）。
+///
+/// 只读取 payload，不验证签名（验证是服务端的事）。
+///
+/// 用于 [ApiConfig.onGetTokenExpiry] 回调，启用 token 主动刷新：
+/// 距过期不足阈值时提前刷新，避免带过期 token 发请求或重连。
+///
+/// ```dart
+/// final expiry = parseJwtExpiry('eyJhbGci...');
+/// if (expiry != null) {
+///   final remaining = expiry.difference(DateTime.now());
+///   print('Token expires in ${remaining.inMinutes} min');
+/// }
+/// ```
+DateTime? parseJwtExpiry(String token) {
+  try {
+    final jwt = JWT.decode(token);
+    final payload = jwt.payload;
+    if (payload is! Map) return null;
+
+    final exp = payload['exp'];
+    if (exp is! int) return null;
+    return DateTime.fromMillisecondsSinceEpoch(exp * 1000);
+  } catch (_) {
+    return null;
+  }
+}
diff --git a/apps/im_app/lib/core/services/socket_manager.dart b/apps/im_app/lib/core/services/socket_manager.dart
index 0049616..a1128dd 100644
--- a/apps/im_app/lib/core/services/socket_manager.dart
+++ b/apps/im_app/lib/core/services/socket_manager.dart
@@ -1,6 +1,5 @@
 import 'dart:async';
 
-
 import 'package:networks_sdk/networks_sdk.dart';
 
 import 'network_backoff_debouncer.dart';
@@ -10,9 +9,8 @@ import 'network_backoff_debouncer.dart';
 /// 参考 HTTP 层 onTokenRefresh 的回调注入模式。
 /// App 层在 Provider 装配时注入解密/解析逻辑，
 /// 不在 SDK 内部调用加解密 SDK。
-typedef MessageTransformer = Map Function(
-  Map raw,
-);
+typedef MessageTransformer =
+    Map Function(Map raw);
 
 /// WebSocket 连接管理
 ///
@@ -39,19 +37,26 @@ typedef MessageTransformer = Map Function(
 ///
 /// ```
 /// 登录成功 → connect(token) → 前置检查 → 建立连接
-/// App 进后台 → onEnterBackground() → 断开连接（省电）
-/// App 回前台 → onEnterForeground() → 检查网络 → 自动重连
+///
+/// ── disconnectInBackground = true（默认，移动端）──
+/// App 进后台 → onEnterBackground() → 暂停心跳 + 断开连接（省电）
+/// App 回前台 → onEnterForeground() → 恢复心跳 → onBeforeReconnect → 重连
+///
+/// ── disconnectInBackground = false（桌面端）──
+/// App 进后台 → onEnterBackground() → 不操作，完全保活
+/// App 回前台 → onEnterForeground() → 不操作（连接始终在线）
+///
 /// 网络丢失 → handleNetworkLost() → 断开连接
-/// 网络恢复 → handleNetworkRestored() → 退避重连（防抖动）
+/// 网络恢复 → handleNetworkRestored() → 退避 → onBeforeReconnect → 重连
 /// 登出 → disconnect() → 断开连接，清除 token
 /// ```
 ///
 /// ## 前置检查策略
 ///
 /// 所有会发起网络操作的方法都先检查前置条件：
-/// - connect → 检查网络可用性 + 是否在后台
-/// - send / sendString → 检查连接状态 + 是否在后台
-/// - onEnterForeground 重连 → 检查网络可用性
+/// - connect → 检查网络可用性 + 是否在后台（仅 disconnectInBackground=true 时拦截）
+/// - send / sendString → 检查连接状态 + 是否在后台（仅 disconnectInBackground=true 时拦截）
+/// - onEnterForeground / 网络恢复重连 → 检查网络可用性 + onBeforeReconnect
 class SocketManager {
   final NetworksMessagingApi _client;
   final String _wsUrl;
@@ -70,6 +75,22 @@ class SocketManager {
   /// 连接和重连前调用，无网络时跳过操作并标记恢复时重试。
   final Future Function()? onCheckNetworkAvailable;
 
+  /// 重连前回调
+  ///
+  /// 在 WebSocket 重连前调用（前台恢复、网络恢复），App 层用于：
+  /// - 检查并刷新即将过期的 token
+  /// - 更新连接参数
+  ///
+  /// 回调完成后才发起实际重连。
+  final Future Function()? onBeforeReconnect;
+
+  /// 进后台时是否断开连接
+  ///
+  /// true（默认）— 后台断连省电，由 push 通知兜底，前台恢复时自动重连。
+  /// false — 后台保持连接（适用于桌面端或需要后台实时推送的场景）。
+  /// 设为 false 时，后台仅暂停心跳，不主动断连。
+  final bool disconnectInBackground;
+
   /// 日志回调
   final void Function(String message, {String? tag})? onLog;
 
@@ -104,10 +125,12 @@ class SocketManager {
     required NetworksMessagingApi client,
     required String wsUrl,
     this.onMessageTransform,
+    this.onBeforeReconnect,
+    this.disconnectInBackground = true,
     this.onCheckNetworkAvailable,
     this.onLog,
-  })  : _client = client,
-        _wsUrl = wsUrl;
+  }) : _client = client,
+       _wsUrl = wsUrl;
 
   // ── 连接 ──────────────────────────────────────────────────────────────────
 
@@ -124,8 +147,8 @@ class SocketManager {
     _reconnectOnForeground = false;
     _reconnectOnNetworkRestore = false;
 
-    // 前置检查：在后台不连接（省电）
-    if (_isInBackground) {
+    // 前置检查：移动端模式下在后台不连接（省电）
+    if (_isInBackground && disconnectInBackground) {
       _reconnectOnForeground = true;
       _log('In background, defer connect to foreground');
       return false;
@@ -165,26 +188,47 @@ class SocketManager {
   /// 当前是否在后台
   bool get isInBackground => _isInBackground;
 
+  /// Token 热更新
+  ///
+  /// 透传给 SocketClient，仅更新内部 token，不断开连接。
+  /// 适用于 HTTP 层 token 刷新后同步到 WebSocket 的场景。
+  void updateToken(String token) {
+    _lastToken = token;
+    _client.updateToken(token);
+    _log('Token updated via SocketManager');
+  }
+
   // ── 前后台生命周期 ────────────────────────────────────────────────────────
   //
-  //   后台 → 断连（省电省流量）
+  //   后台 → 断连（省电省流量）或保持连接（桌面端）
   //   前台 → 自动重连（如果之前有连接）
 
-  /// App 进后台 → 断开连接，标记前台恢复时重连
+  /// App 进后台
   ///
   /// 由 App 层 WidgetsBindingObserver 在 [AppLifecycleState.paused] 时调用。
-  /// 后台保持连接会消耗电量和流量，断开后由 push 通知兜底。
+  ///
+  /// [disconnectInBackground] 为 true 时（默认，移动端）：
+  /// 断开连接 + 暂停心跳，由 push 通知兜底，前台恢复时自动重连。
+  ///
+  /// [disconnectInBackground] 为 false 时（桌面端）：
+  /// 不断连、不暂停心跳，WebSocket 完全保活。
   void onEnterBackground() {
     _isInBackground = true;
     // 取消待执行的前台重连（防止快速 前台→后台 切换导致后台建连）
     _foregroundReconnectTimer?.cancel();
     _foregroundReconnectTimer = null;
-    // 同步 SocketClient 内部状态（与 onEnterForeground 对称）
+
+    if (!disconnectInBackground) {
+      // 桌面端模式：不断连、不暂停心跳，完全保活
+      _log('Entering background, keeping connection alive');
+      return;
+    }
+
+    // 移动端模式：通知 SocketClient 进后台（暂停心跳）
     _client.onEnterBackground();
 
     if (_lastToken == null) return; // 未登录，无需处理
 
-    // 与 _handleNetworkLost 保持一致：
     // 不仅 connected，connecting / reconnecting 也要断开，
     // 防止 SocketClient 在后台继续尝试连接浪费电量和流量。
     if (_client.isConnected ||
@@ -202,7 +246,11 @@ class SocketManager {
   /// 重连前检查网络可用性，无网络时延迟到网络恢复事件再连。
   void onEnterForeground() {
     _isInBackground = false;
-    _client.onEnterForeground();
+
+    // 只在移动端模式（后台曾断连/暂停心跳）时通知 SocketClient 恢复
+    if (disconnectInBackground) {
+      _client.onEnterForeground();
+    }
 
     if (_reconnectOnForeground && _lastToken != null) {
       _reconnectOnForeground = false;
@@ -226,7 +274,12 @@ class SocketManager {
               _log('Network unavailable, defer reconnect to network restore');
               return;
             }
-            _client.connect(_wsUrl, token: _lastToken!);
+            // 重连前钩子：刷新即将过期的 token 等
+            await onBeforeReconnect?.call();
+            // token 可能被 onBeforeReconnect 更新（通过 updateToken 链路同步）
+            if (_lastToken != null && !_client.isConnected) {
+              _client.connect(_wsUrl, token: _lastToken!);
+            }
           }
         },
       );
@@ -275,18 +328,22 @@ class SocketManager {
     if (_reconnectOnNetworkRestore && _lastToken != null) {
       _reconnectOnNetworkRestore = false;
 
-      // 在后台不重连，等前台恢复时再连
-      if (_isInBackground) {
+      // 移动端模式：在后台不重连，等前台恢复时再连
+      if (_isInBackground && disconnectInBackground) {
         _reconnectOnForeground = true;
         _log('Network restored but in background, defer to foreground');
         return;
       }
 
       _log('Network restored, scheduling reconnect with backoff');
-      _networkDebouncer.call(() {
+      _networkDebouncer.call(() async {
         if (!_client.isConnected && _lastToken != null && !_isInBackground) {
-          _log('Backoff timer fired, reconnecting');
-          _client.connect(_wsUrl, token: _lastToken!);
+          // 重连前钩子：刷新即将过期的 token 等
+          await onBeforeReconnect?.call();
+          if (!_client.isConnected && _lastToken != null && !_isInBackground) {
+            _log('Backoff timer fired, reconnecting');
+            _client.connect(_wsUrl, token: _lastToken!);
+          }
         }
       });
     }
@@ -308,6 +365,9 @@ class SocketManager {
   /// 原始消息流（不经预处理，调试用）
   Stream get rawMessageStream => _client.rawMessageStream;
 
+  /// 二进制消息流
+  Stream get binaryMessageStream => _client.binaryMessageStream;
+
   /// 连接状态变化流
   Stream get connectionStateStream =>
       _client.connectionStateStream;
@@ -333,6 +393,14 @@ class SocketManager {
     return _client.sendString(message);
   }
 
+  /// 发送二进制数据
+  ///
+  /// 前置检查：未连接或在后台时不发送。
+  Future sendBytes(List bytes) {
+    if (!_canSend()) return Future.value(false);
+    return _client.sendBytes(bytes);
+  }
+
   // ── 释放 ──────────────────────────────────────────────────────────────────
 
   /// 释放所有资源
@@ -355,7 +423,7 @@ class SocketManager {
       _log('Not connected, cannot send');
       return false;
     }
-    if (_isInBackground) {
+    if (_isInBackground && disconnectInBackground) {
       _log('In background, skip send');
       return false;
     }
diff --git a/apps/im_app/lib/core/ui/base/assets.dart b/apps/im_app/lib/core/ui/base/assets.dart
new file mode 100644
index 0000000..5b6122f
--- /dev/null
+++ b/apps/im_app/lib/core/ui/base/assets.dart
@@ -0,0 +1,30 @@
+/// 静态资源路径常量，统一维护，避免路径字符串散落在业务代码中。
+///
+/// 所有路径须与 pubspec.yaml 的 flutter.assets 声明保持一致。
+/// 新增资源：① 文件放入 assets/ ② pubspec.yaml 声明 ③ 此处加常量。
+///
+/// 渲染逻辑（缓存、占位、错误态）由 core/ui/components/ 下的组件负责，不在此处封装。
+///
+/// ## 使用
+/// ```dart
+/// Image.asset(AppAssets.logo)
+/// Image.asset(AppAssets.logo, width: 80, fit: BoxFit.cover)
+/// ```
+abstract final class AppAssets {
+  AppAssets._();
+
+  // ── 品牌 ──────────────────────────────────────────────────
+  static const logo = 'assets/images/logo.png';
+  static const logoLight = 'assets/images/logo_light.png';
+
+  // ── 占位图 ────────────────────────────────────────────────
+  static const avatarPlaceholder = 'assets/images/avatar_placeholder.png';
+
+  // ── 空状态插图（SVG，引入 flutter_svg 后启用） ─────────────
+  // static const emptyChat        = 'assets/svg/empty_chat.svg';
+  // static const emptyContact     = 'assets/svg/empty_contact.svg';
+  // static const emptySearch      = 'assets/svg/empty_search.svg';
+
+  // ── 动画 ──────────────────────────────────────────────────
+  // static const loading          = 'assets/gif/loading.gif';
+}
diff --git a/apps/im_app/lib/core/ui/base/icons.dart b/apps/im_app/lib/core/ui/base/icons.dart
new file mode 100644
index 0000000..eb1bb6a
--- /dev/null
+++ b/apps/im_app/lib/core/ui/base/icons.dart
@@ -0,0 +1,44 @@
+import 'package:flutter/material.dart';
+
+/// 项目图标常量，统一维护，避免 Icons.xxx 散落在业务代码中。
+///
+/// 渲染逻辑（大小、颜色、点击态）由调用方负责，不在此处封装。
+///
+/// ## 使用
+/// ```dart
+/// Icon(AppIcons.send)
+/// Icon(AppIcons.send, size: 20, color: Colors.white)
+/// IconButton(icon: Icon(AppIcons.back), onPressed: ...)
+/// ```
+abstract final class AppIcons {
+  AppIcons._();
+
+  // ── 底部导航 ──────────────────────────────────────────────
+  static const chat = Icons.chat_bubble_outline_rounded;
+  static const contact = Icons.people_outline_rounded;
+  static const settings = Icons.settings_outlined;
+
+  // ── 通用操作 ──────────────────────────────────────────────
+  static const back = Icons.arrow_back_ios_new_rounded;
+  static const close = Icons.close_rounded;
+  static const more = Icons.more_horiz_rounded;
+  static const search = Icons.search_rounded;
+  static const add = Icons.add_rounded;
+
+  // ── 聊天输入区 ────────────────────────────────────────────
+  static const send = Icons.send_rounded;
+  static const attach = Icons.attach_file_rounded;
+  static const emoji = Icons.emoji_emotions_outlined;
+  static const camera = Icons.camera_alt_outlined;
+  static const voice = Icons.mic_outlined;
+
+  // ── 用户 / 联系人 ─────────────────────────────────────────
+  static const avatar = Icons.account_circle_outlined;
+  static const addUser = Icons.person_add_outlined;
+
+  // ── 状态反馈 ──────────────────────────────────────────────
+  static const success = Icons.check_circle_outline_rounded;
+  static const warning = Icons.warning_amber_rounded;
+  static const error = Icons.error_outline_rounded;
+  static const info = Icons.info_outline_rounded;
+}
diff --git a/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart b/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart
index da6fa16..14f44d3 100644
--- a/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart
+++ b/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart
@@ -1,7 +1,6 @@
 import 'dart:math';
 
 import 'package:drift/drift.dart';
-import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:im_app/app/di/db_provider.dart';
 import 'package:im_app/data/local/drift/app_database.dart';
@@ -45,13 +44,12 @@ class ChatDbTestState {
 
 @riverpod
 class ChatDbTestViewModel extends _$ChatDbTestViewModel {
-
   @override
   ChatDbTestState build() {
     // 这里就是 onInit
     final List testResults = List.generate(
       1000,
-          (i) => TestResult(
+      (i) => TestResult(
         title: '用户 ${Random().nextInt(9999)}',
         subtitle: 'uid: ${Random().nextInt(999999)}',
         duration: '${Random().nextInt(500)}ms',
@@ -86,7 +84,7 @@ class ChatDbTestViewModel extends _$ChatDbTestViewModel {
     for (var i = 0; i < count; i += chunkSize) {
       final chunk = List.generate(
         chunkSize.clamp(0, count - i),
-            (j) => UsersCompanion.insert(
+        (j) => UsersCompanion.insert(
           uid: Value(i + j),
           nickname: Value('User ${i + j}'),
         ),
@@ -98,13 +96,13 @@ class ChatDbTestViewModel extends _$ChatDbTestViewModel {
       // 让出主线程
       await Future.delayed(Duration.zero);
 
-      debugPrint('已完成: $completed / $count (${stopwatch.elapsedMilliseconds}ms)');
+      debugPrint(
+        '已完成: $completed / $count (${stopwatch.elapsedMilliseconds}ms)',
+      );
 
       // 更新 UI 状态
       if (ref.mounted) {
-        state = state.copyWith(
-          currentState: '已插入 $completed / $count 条',
-        );
+        state = state.copyWith(currentState: '已插入 $completed / $count 条');
       }
     }
 
@@ -116,4 +114,4 @@ class ChatDbTestViewModel extends _$ChatDbTestViewModel {
       );
     }
   }
-}
\ No newline at end of file
+}
diff --git a/apps/im_app/lib/features/chat/view/chat_detail_page.dart b/apps/im_app/lib/features/chat/view/chat_detail_page.dart
index 7f2be5d..23709ec 100644
--- a/apps/im_app/lib/features/chat/view/chat_detail_page.dart
+++ b/apps/im_app/lib/features/chat/view/chat_detail_page.dart
@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../../../../core/ui/base/context_theme_ext.dart';
 
@@ -12,7 +13,7 @@ import '../../../../core/ui/base/context_theme_ext.dart';
 ///
 /// 将 [conversationId] 传给对应的 Riverpod `.family` provider 加载完整会话数据。
 /// 构造参数保持不变，数据来源从 `extra` 换成 provider 即可。
-class ChatDetailPage extends StatelessWidget {
+class ChatDetailPage extends ConsumerWidget {
   const ChatDetailPage({
     super.key,
     required this.conversationId,
@@ -23,7 +24,7 @@ class ChatDetailPage extends StatelessWidget {
   final String title;
 
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final s = context.styles;
 
     return Scaffold(
diff --git a/apps/im_app/lib/features/chat/view/chat_page.dart b/apps/im_app/lib/features/chat/view/chat_page.dart
index ce264a2..590a65b 100644
--- a/apps/im_app/lib/features/chat/view/chat_page.dart
+++ b/apps/im_app/lib/features/chat/view/chat_page.dart
@@ -20,8 +20,6 @@ class ChatPage extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
-    final vm = ref.read(chatViewModelProvider.notifier);
-
     return Scaffold(
       appBar: AppBar(title: const Text('聊天')),
       body: Center(
@@ -32,36 +30,48 @@ class ChatPage extends ConsumerWidget {
             // 切换 Tab：用 go，替换整个历史栈，不可返回
             AppButton.inverse(
               label: '切换 Tab（go）',
-              onPressed: () => vm.goToContact(context),
+              onPressed: () =>
+                  ref.read(chatViewModelProvider.notifier).goToContact(context),
             ),
             // 带参数 push：extra 传 Dart Record，适合已有对象的场景
             AppButton.inverse(
               label: '有参 push（extra）',
-              onPressed: () => vm.pushChatDetailWithExtra(context),
+              onPressed: () => ref
+                  .read(chatViewModelProvider.notifier)
+                  .pushChatDetailWithExtra(context),
             ),
             // 带参数 push：id 内嵌在路径中，适合需要深链接 / 分享的场景
             AppButton.inverse(
               label: '有参 push（路径参数）',
-              onPressed: () => vm.pushChatDetailById(context),
+              onPressed: () => ref
+                  .read(chatViewModelProvider.notifier)
+                  .pushChatDetailById(context),
             ),
             // 无参 push：压栈，自动显示返回按钮，不切 Tab
             AppButton.inverse(
               label: '无参 push',
-              onPressed: () => vm.pushSettingsTheme(context),
+              onPressed: () => ref
+                  .read(chatViewModelProvider.notifier)
+                  .pushSettingsTheme(context),
             ),
             // 无参 go：替换历史，切换到对应 Tab，TabBar 可见，不可返回
             AppButton.inverse(
               label: '无参 go',
-              onPressed: () => vm.goToSettings(context),
+              onPressed: () => ref
+                  .read(chatViewModelProvider.notifier)
+                  .goToSettings(context),
             ),
             AppButton.inverse(
               label: '测试数据库性能',
-              onPressed: () => vm.goToDatabaseTest(context),
+              onPressed: () => ref
+                  .read(chatViewModelProvider.notifier)
+                  .goToDatabaseTest(context),
             ),
             AppButton.secondary(
               label: '退出登录',
               fullWidth: false,
-              onPressed: () => vm.logout(),
+              onPressed: () =>
+                  ref.read(chatViewModelProvider.notifier).logout(),
             ),
           ],
         ),
diff --git a/apps/im_app/lib/features/contact/view/contact_page.dart b/apps/im_app/lib/features/contact/view/contact_page.dart
index 7e819a1..d4a4912 100644
--- a/apps/im_app/lib/features/contact/view/contact_page.dart
+++ b/apps/im_app/lib/features/contact/view/contact_page.dart
@@ -1,13 +1,14 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 /// 联系人页占位
 ///
 /// 待 contact 功能开发后替换为实际内容。
-class ContactPage extends StatelessWidget {
+class ContactPage extends ConsumerWidget {
   const ContactPage({super.key});
 
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     return const Scaffold();
   }
 }
diff --git a/apps/im_app/lib/features/login/di/auth_providers.dart b/apps/im_app/lib/features/login/di/auth_providers.dart
index 10a8068..8802f93 100644
--- a/apps/im_app/lib/features/login/di/auth_providers.dart
+++ b/apps/im_app/lib/features/login/di/auth_providers.dart
@@ -12,7 +12,7 @@ import '../usecases/login_usecase.dart';
 /// ViewModel Provider 由 `@riverpod` 注解自动生成，不在此文件中。
 ///
 /// Auth 模块的 DI 链路：Repository → UseCase（按需）。
-/// app/di/ 只提供 SDK 基础设施（apiConfig / apiClient / socketManager / storageApi），
+/// app/di/ 只提供 SDK 基础设施（apiConfig / networkSdkApi / socketManager / storageApi），
 /// 业务模块的 Provider 内聚在 features/{模块}/di/ 下。
 ///
 /// ```
@@ -21,7 +21,7 @@ import '../usecases/login_usecase.dart';
 ///     → ref.read(authRepositoryProvider)   ← di/ 手动装配
 ///     → ref.read(socketManagerProvider)    ← app/di/ 手动装配
 ///     → ref.read(apiConfigProvider)        ← app/di/ 手动装配
-///       → ref.read(apiClientProvider)      ← app/di/ 手动装配
+///       → ref.read(networkSdkApiProvider)  ← app/di/ 手动装配
 ///     → ref.read(storageSdkProvider)       ← app/di/ 手动装配
 /// ```
 
@@ -41,7 +41,7 @@ final authRepositoryProvider = Provider((ref) {
   // TODO: final secureStorage = ref.read(secureStorageProvider);
 
   return AuthRepositoryImpl(
-    client: ref.read(networkSdkApiProvider), // 直接注入 ApiClient
+    client: ref.read(networkSdkApiProvider), // 注入 Facade 接口
     onTokenUpdate: (token) {
       apiConfig.updateToken(token); // 内存（network_sdk）
       // TODO: secureStorage.saveToken(token); // 持久化（crypto_sdk）
diff --git a/apps/im_app/lib/features/login/presentation/login_view_model.dart b/apps/im_app/lib/features/login/presentation/login_view_model.dart
index f1de73c..ec4e928 100644
--- a/apps/im_app/lib/features/login/presentation/login_view_model.dart
+++ b/apps/im_app/lib/features/login/presentation/login_view_model.dart
@@ -29,7 +29,7 @@ part 'login_view_model.g.dart';
 /// loginViewModelProvider                    ← @riverpod 自动生成（本文件）
 ///   → ref.read(loginUseCaseProvider)       ← di/ 手动装配
 ///     → ref.read(authRepositoryProvider)   ← di/ 手动装配
-///       → ref.read(apiClientProvider)      ← app/di/ 手动装配
+///       → ref.read(networkSdkApiProvider)  ← app/di/ 手动装配
 /// ```
 ///
 /// ## 数据流位置
@@ -56,6 +56,7 @@ class LoginViewModel extends _$LoginViewModel {
   /// 正式 [login] 成功后同样需要调用 [AuthNotifier.login] 更新守卫状态。
   Future demoLogin() async {
     final storageApi = ref.read(storageSdkProvider);
+
     ///TODO: StorageSDKLifeCycle 需要只在主项目暴露
     final storageLifeCycle = storageApi as StorageSdkLifecycle;
     ref.read(authNotifierProvider).login();
@@ -76,10 +77,9 @@ class LoginViewModel extends _$LoginViewModel {
     state = state.copyWith(isLoading: true, error: null);
 
     try {
-      final user = await ref.read(loginUseCaseProvider).execute(
-            email: email,
-            password: password,
-          );
+      final user = await ref
+          .read(loginUseCaseProvider)
+          .execute(email: email, password: password);
 
       state = state.copyWith(user: user, isLoading: false);
     } on FormatException catch (e) {
diff --git a/apps/im_app/macos/Podfile b/apps/im_app/macos/Podfile
index a46f7f2..6fd2b20 100644
--- a/apps/im_app/macos/Podfile
+++ b/apps/im_app/macos/Podfile
@@ -1,4 +1,4 @@
-platform :osx, '11.0'
+platform :osx, '14.0'
 
 # CocoaPods analytics sends network stats synchronously affecting flutter build latency.
 ENV['COCOAPODS_DISABLE_STATS'] = 'true'
@@ -38,5 +38,8 @@ end
 post_install do |installer|
   installer.pods_project.targets.each do |target|
     flutter_additional_macos_build_settings(target)
+    target.build_configurations.each do |config|
+      config.build_settings['SWIFT_VERSION'] ||= '6.2'
+    end
   end
 end
diff --git a/apps/im_app/macos/Runner.xcodeproj/project.pbxproj b/apps/im_app/macos/Runner.xcodeproj/project.pbxproj
index fecd0db..3208875 100644
--- a/apps/im_app/macos/Runner.xcodeproj/project.pbxproj
+++ b/apps/im_app/macos/Runner.xcodeproj/project.pbxproj
@@ -481,7 +481,7 @@
 				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = com.cusotmer.im.imApp.RunnerTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/im_app.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/im_app";
 			};
 			name = Debug;
@@ -496,7 +496,7 @@
 				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = com.cusotmer.im.imApp.RunnerTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/im_app.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/im_app";
 			};
 			name = Release;
@@ -511,7 +511,7 @@
 				MARKETING_VERSION = 1.0;
 				PRODUCT_BUNDLE_IDENTIFIER = com.cusotmer.im.imApp.RunnerTests;
 				PRODUCT_NAME = "$(TARGET_NAME)";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 				TEST_HOST = "$(BUILT_PRODUCTS_DIR)/im_app.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/im_app";
 			};
 			name = Profile;
@@ -557,7 +557,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				MACOSX_DEPLOYMENT_TARGET = 11.0;
+				MACOSX_DEPLOYMENT_TARGET = 14.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = macosx;
 				SWIFT_COMPILATION_MODE = wholemodule;
@@ -580,7 +580,7 @@
 					"@executable_path/../Frameworks",
 				);
 				PROVISIONING_PROFILE_SPECIFIER = "";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 			};
 			name = Profile;
 		};
@@ -639,7 +639,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				MACOSX_DEPLOYMENT_TARGET = 11.0;
+				MACOSX_DEPLOYMENT_TARGET = 14.0;
 				MTL_ENABLE_DEBUG_INFO = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = macosx;
@@ -689,7 +689,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				MACOSX_DEPLOYMENT_TARGET = 11.0;
+				MACOSX_DEPLOYMENT_TARGET = 14.0;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = macosx;
 				SWIFT_COMPILATION_MODE = wholemodule;
@@ -713,7 +713,7 @@
 				);
 				PROVISIONING_PROFILE_SPECIFIER = "";
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 			};
 			name = Debug;
 		};
@@ -732,7 +732,7 @@
 					"@executable_path/../Frameworks",
 				);
 				PROVISIONING_PROFILE_SPECIFIER = "";
-				SWIFT_VERSION = 5.0;
+				SWIFT_VERSION = 6.2;
 			};
 			name = Release;
 		};
diff --git a/apps/im_app/pubspec.yaml b/apps/im_app/pubspec.yaml
index e02f3fb..b20f848 100644
--- a/apps/im_app/pubspec.yaml
+++ b/apps/im_app/pubspec.yaml
@@ -37,9 +37,13 @@ dependencies:
   # 网络状态监听
   connectivity_plus: ^6.1.0
 
+  # JWT 解析（token 过期检测、主动刷新）
+  dart_jsonwebtoken: ^3.3.2
+
   # 数据库（schema 定义在 im_app，连接/CRUD 封装在 storage_sdk）
   drift: ^2.22.0
 
+
 dev_dependencies:
   flutter_test:
     sdk: flutter
diff --git a/packages/cipher_guard_sdk/android/build.gradle b/packages/cipher_guard_sdk/android/build.gradle
deleted file mode 100644
index 60bf876..0000000
--- a/packages/cipher_guard_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.cipher_guard_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.cipher_guard_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/cipher_guard_sdk/android/build.gradle.kts b/packages/cipher_guard_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..9360f2b
--- /dev/null
+++ b/packages/cipher_guard_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.cipher_guard_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.cipher_guard_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/cipher_guard_sdk/ios/Classes/CipherGuardSdkPlugin.swift b/packages/cipher_guard_sdk/ios/Classes/CipherGuardSdkPlugin.swift
index 4cfabae..51614bd 100644
--- a/packages/cipher_guard_sdk/ios/Classes/CipherGuardSdkPlugin.swift
+++ b/packages/cipher_guard_sdk/ios/Classes/CipherGuardSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class CipherGuardSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/cipher_guard_sdk/ios/cipher_guard_sdk.podspec b/packages/cipher_guard_sdk/ios/cipher_guard_sdk.podspec
index 8f648dd..a44f3dd 100644
--- a/packages/cipher_guard_sdk/ios/cipher_guard_sdk.podspec
+++ b/packages/cipher_guard_sdk/ios/cipher_guard_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart b/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart
index ff455ba..481bad3 100644
--- a/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart
+++ b/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart
@@ -29,23 +29,25 @@ class EncryptionFlutterService {
       // Get secure random
       final secureRandom = FortunaRandom();
       secureRandom.seed(KeyParameter(_generateSecureRandomBytes(32)));
-      
+
       // Create RSA key generator
       final keyGen = RSAKeyGenerator();
-      keyGen.init(ParametersWithRandom(
-        RSAKeyGeneratorParameters(BigInt.parse('65537'), keySize, 64),
-        secureRandom,
-      ));
-      
+      keyGen.init(
+        ParametersWithRandom(
+          RSAKeyGeneratorParameters(BigInt.parse('65537'), keySize, 64),
+          secureRandom,
+        ),
+      );
+
       // Generate key pair
       final keyPair = keyGen.generateKeyPair();
-      final rsaPublicKey = keyPair.publicKey as RSAPublicKey;
-      final rsaPrivateKey = keyPair.privateKey as RSAPrivateKey;
-      
+      final rsaPublicKey = keyPair.publicKey;
+      final rsaPrivateKey = keyPair.privateKey;
+
       // Export to PEM format
       final publicKeyPem = _encodeRSAPublicKey(rsaPublicKey);
       final privateKeyPem = _encodeRSAPrivateKey(rsaPrivateKey);
-      
+
       return RsaKeyPairResult(
         publicKey: publicKeyPem,
         privateKey: privateKeyPem,
@@ -59,18 +61,18 @@ class EncryptionFlutterService {
   String _encodeRSAPublicKey(RSAPublicKey publicKey) {
     // Build RSAPublicKeyInfo structure
     final topSeq = ASN1Sequence();
-    
+
     // AlgorithmIdentifier: OID 1.2.840.113549.1.1.1 + NULL
     final algoSeq = ASN1Sequence();
     algoSeq.add(ASN1ObjectIdentifier([1, 2, 840, 113549, 1, 1, 1])); // RSA
     algoSeq.add(ASN1Null());
     topSeq.add(algoSeq);
-    
+
     // RSAPublicKey: modulus + publicExponent
     final keySeq = ASN1Sequence();
     keySeq.add(ASN1Integer(publicKey.n!));
     keySeq.add(ASN1Integer(publicKey.exponent!));
-    
+
     // BitString wrapping the key (with 0 unused bits prefix)
     final keyBytes = keySeq.encodedBytes;
     final keyList = List.from(keyBytes);
@@ -86,27 +88,27 @@ class EncryptionFlutterService {
   String _encodeRSAPrivateKey(RSAPrivateKey privateKey) {
     // Build RSAPrivateKey structure (PKCS#8 format)
     final topSeq = ASN1Sequence();
-    
+
     // Version (0)
     topSeq.add(ASN1Integer(BigInt.zero));
-    
+
     // Modulus
     topSeq.add(ASN1Integer(privateKey.n!));
-    
+
     // Public Exponent
     topSeq.add(ASN1Integer(privateKey.exponent!));
-    
+
     // Private Exponent
     topSeq.add(ASN1Integer(privateKey.privateExponent!));
-    
+
     // Prime P
     topSeq.add(ASN1Integer(privateKey.p!));
-    
+
     // Prime Q
     topSeq.add(ASN1Integer(privateKey.q!));
-    
+
     // (Optional CRT params omitted for simplicity)
-    
+
     final derBytes = topSeq.encodedBytes;
     final base64 = base64Encode(derBytes.toList());
     return '-----BEGIN PRIVATE KEY-----\n$base64\n-----END PRIVATE KEY-----';
@@ -122,24 +124,24 @@ class EncryptionFlutterService {
     try {
       // Generate AES key from MD5(password)
       final aesKey = _md5Hash(password);
-      
+
       // Generate random IV (16 bytes)
       final iv = _generateSecureRandomBytes(16);
-      
+
       // AES encrypt using encrypt package
       final secretKey = encrypt_pkg.Key(aesKey);
       final encryptor = encrypt_pkg.Encrypter(
         encrypt_pkg.AES(secretKey, mode: encrypt_pkg.AESMode.cbc),
       );
-      
+
       final encrypted = encryptor.encrypt(privateKey, iv: encrypt_pkg.IV(iv));
       final encryptedBytes = encrypted.bytes;
-      
+
       // Combine IV + encrypted data
       final combined = Uint8List(iv.length + encryptedBytes.length);
       combined.setAll(0, iv);
       combined.setAll(iv.length, encryptedBytes);
-      
+
       return base64Encode(combined);
     } catch (e) {
       throw Exception('Failed to encrypt private key: $e');
@@ -154,25 +156,25 @@ class EncryptionFlutterService {
     try {
       // Generate AES key from MD5(password)
       final aesKey = _md5Hash(password);
-      
+
       // Decode Base64
       final combined = base64Decode(encryptedPrivateKey);
-      
+
       // Extract IV and encrypted data
       final iv = combined.sublist(0, 16);
       final encBytes = combined.sublist(16);
-      
+
       // AES decrypt
       final secretKey = encrypt_pkg.Key(aesKey);
       final encryptor = encrypt_pkg.Encrypter(
         encrypt_pkg.AES(secretKey, mode: encrypt_pkg.AESMode.cbc),
       );
-      
+
       final decrypted = encryptor.decrypt(
         encrypt_pkg.Encrypted(encBytes),
         iv: encrypt_pkg.IV(iv),
       );
-      
+
       return decrypted;
     } catch (e) {
       throw Exception('Failed to decrypt private key: $e');
@@ -185,11 +187,8 @@ class EncryptionFlutterService {
   SessionKeyResult generateSessionKey({int initialRound = 1}) {
     final keyBytes = _generateSecureRandomBytes(sessionKeySize);
     final key = base64Encode(keyBytes);
-    
-    return SessionKeyResult(
-      key: key,
-      round: initialRound,
-    );
+
+    return SessionKeyResult(key: key, round: initialRound);
   }
 
   /// Encrypt session key with RSA public key
@@ -200,11 +199,11 @@ class EncryptionFlutterService {
     try {
       // Parse RSA public key
       final rsaPublicKey = _parsePublicKey(publicKey);
-      
+
       // RSA encrypt using PKCS1 padding (like native implementations)
       final cipher = PKCS1Encoding(RSAEngine());
       cipher.init(true, PublicKeyParameter(rsaPublicKey));
-      
+
       final encryptedBytes = cipher.process(utf8.encode(sessionKey));
       return base64Encode(encryptedBytes);
     } catch (e) {
@@ -220,11 +219,11 @@ class EncryptionFlutterService {
     try {
       // Parse RSA private key
       final rsaPrivateKey = _parsePrivateKey(privateKey);
-      
+
       // RSA decrypt using PKCS1 padding (like native implementations)
       final cipher = PKCS1Encoding(RSAEngine());
       cipher.init(false, PrivateKeyParameter(rsaPrivateKey));
-      
+
       final decryptedBytes = cipher.process(base64Decode(encryptedSessionKey));
       return utf8.decode(decryptedBytes);
     } catch (e) {
@@ -243,30 +242,27 @@ class EncryptionFlutterService {
     try {
       // Derive key for round
       final actualKey = _deriveKeyForRound(sessionKey, round);
-      
+
       // Generate random IV (16 bytes for CTR)
       final iv = _generateSecureRandomBytes(16);
-      
+
       // AES-CTR encrypt
       final secretKey = encrypt_pkg.Key(actualKey);
       final encryptor = encrypt_pkg.Encrypter(
         encrypt_pkg.AES(secretKey, mode: encrypt_pkg.AESMode.ctr),
       );
-      
+
       final encrypted = encryptor.encrypt(plaintext, iv: encrypt_pkg.IV(iv));
       final encryptedBytes = encrypted.bytes;
-      
+
       // Combine IV + encrypted data
       final combined = Uint8List(iv.length + encryptedBytes.length);
       combined.setAll(0, iv);
       combined.setAll(iv.length, encryptedBytes);
-      
+
       final data = base64Encode(combined);
-      
-      return EncryptedMessageResult(
-        round: round,
-        data: data,
-      );
+
+      return EncryptedMessageResult(round: round, data: data);
     } catch (e) {
       throw Exception('Failed to encrypt message: $e');
     }
@@ -281,25 +277,25 @@ class EncryptionFlutterService {
     try {
       // Derive key for round
       final actualKey = _deriveKeyForRound(sessionKey, round);
-      
+
       // Decode Base64
       final combined = base64Decode(encryptedData);
-      
+
       // Extract IV and encrypted data
       final iv = combined.sublist(0, 16);
       final encBytes = combined.sublist(16);
-      
+
       // AES-CTR decrypt
       final secretKey = encrypt_pkg.Key(actualKey);
       final encryptor = encrypt_pkg.Encrypter(
         encrypt_pkg.AES(secretKey, mode: encrypt_pkg.AESMode.ctr),
       );
-      
+
       final decrypted = encryptor.decrypt(
         encrypt_pkg.Encrypted(encBytes),
         iv: encrypt_pkg.IV(iv),
       );
-      
+
       return decrypted;
     } catch (e) {
       throw Exception('Failed to decrypt message: $e');
@@ -316,36 +312,34 @@ class EncryptionFlutterService {
   String? _aesSecret;
 
   /// Decrypt push notification (AES-GCM)
-  String decryptPushNotification({
-    required String encryptedData,
-  }) {
+  String decryptPushNotification({required String encryptedData}) {
     try {
       final secret = _aesSecret;
       if (secret == null) {
         throw Exception('AES_SECRET not set');
       }
-      
+
       // Convert hex string to bytes
       final secretBytes = _hexStringToBytes(secret);
-      
+
       // Decode Base64
       final combined = base64Decode(encryptedData);
-      
+
       // Extract IV and encrypted data
       final iv = combined.sublist(0, gcmIvLength);
       final encBytes = combined.sublist(gcmIvLength);
-      
+
       // AES-GCM decrypt
       final secretKey = encrypt_pkg.Key(secretBytes);
       final encryptor = encrypt_pkg.Encrypter(
         encrypt_pkg.AES(secretKey, mode: encrypt_pkg.AESMode.gcm),
       );
-      
+
       final decrypted = encryptor.decrypt(
         encrypt_pkg.Encrypted(encBytes),
         iv: encrypt_pkg.IV(iv),
       );
-      
+
       return decrypted;
     } catch (e) {
       throw Exception('Failed to decrypt push notification: $e');
@@ -375,10 +369,10 @@ class EncryptionFlutterService {
   Uint8List _deriveKeyForRound(String sessionKey, int targetRound) {
     // Base64 decode session key
     final keyBytes = base64Decode(sessionKey);
-    
+
     // Apply MD5 for the round (simplified version)
     final hash = md5.convert(keyBytes).bytes as Uint8List;
-    
+
     return hash;
   }
 
@@ -390,19 +384,19 @@ class EncryptionFlutterService {
         .replaceAll('\n', '')
         .trim();
     final bytes = base64Decode(base64);
-    
+
     // Parse ASN.1 DER format
     final asn1Parser = ASN1Parser(Uint8List.fromList(bytes));
     final topLevelSeq = asn1Parser.nextObject() as ASN1Sequence;
-    
+
     final subjectPublicKeyInfo = topLevelSeq.elements[1] as ASN1BitString;
     final keyBytes = subjectPublicKeyInfo.contentBytes();
     final keyParser = ASN1Parser(Uint8List.fromList(keyBytes));
     final keySeq = keyParser.nextObject() as ASN1Sequence;
-    
+
     final modulus = keySeq.elements[0] as ASN1Integer;
     final publicExponent = keySeq.elements[1] as ASN1Integer;
-    
+
     return RSAPublicKey(
       modulus.valueAsBigInteger,
       publicExponent.valueAsBigInteger,
@@ -417,11 +411,11 @@ class EncryptionFlutterService {
         .replaceAll('\n', '')
         .trim();
     final bytes = base64Decode(base64);
-    
+
     // Parse ASN.1 DER format
     final asn1Parser = ASN1Parser(Uint8List.fromList(bytes));
     final keySeq = asn1Parser.nextObject() as ASN1Sequence;
-    
+
     final modulus = keySeq.elements[1] as ASN1Integer;
     final privateExponent = keySeq.elements[3] as ASN1Integer;
     final p = keySeq.elements[4] as ASN1Integer;
@@ -440,7 +434,9 @@ class EncryptionFlutterService {
     final len = hex.length;
     final data = Uint8List(len ~/ 2);
     for (var i = 0; i < len; i += 2) {
-      data[i ~/ 2] = (int.parse(hex[i], radix: 16) << 4) + int.parse(hex[i + 1], radix: 16);
+      data[i ~/ 2] =
+          (int.parse(hex[i], radix: 16) << 4) +
+          int.parse(hex[i + 1], radix: 16);
     }
     return data;
   }
@@ -468,4 +464,3 @@ class EncryptedMessageResult {
 
   EncryptedMessageResult({required this.round, required this.data});
 }
-
diff --git a/packages/im_log_sdk/android/build.gradle.kts b/packages/im_log_sdk/android/build.gradle.kts
index 0544edc..7e8555a 100644
--- a/packages/im_log_sdk/android/build.gradle.kts
+++ b/packages/im_log_sdk/android/build.gradle.kts
@@ -7,7 +7,6 @@ buildscript {
         google()
         mavenCentral()
     }
-
     dependencies {
         classpath("com.android.tools.build:gradle:8.11.1")
         classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
@@ -23,12 +22,11 @@ allprojects {
 
 plugins {
     id("com.android.library")
-    id("kotlin-android")
+    id("org.jetbrains.kotlin.android")
 }
 
 android {
     namespace = "com.example.im_log_sdk"
-
     compileSdk = 36
 
     compileOptions {
@@ -36,17 +34,9 @@ android {
         targetCompatibility = JavaVersion.VERSION_17
     }
 
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17.toString()
-    }
-
     sourceSets {
-        getByName("main") {
-            java.srcDirs("src/main/kotlin")
-        }
-        getByName("test") {
-            java.srcDirs("src/test/kotlin")
-        }
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
     }
 
     defaultConfig {
@@ -58,9 +48,7 @@ android {
             isIncludeAndroidResources = true
             all {
                 it.useJUnitPlatform()
-
                 it.outputs.upToDateWhen { false }
-
                 it.testLogging {
                     events("passed", "skipped", "failed", "standardOut", "standardError")
                     showStandardStreams = true
@@ -70,6 +58,12 @@ android {
     }
 }
 
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
 dependencies {
     testImplementation("org.jetbrains.kotlin:kotlin-test")
     testImplementation("org.mockito:mockito-core:5.0.0")
diff --git a/packages/im_log_sdk/ios/Classes/ImLogSdkPlugin.swift b/packages/im_log_sdk/ios/Classes/ImLogSdkPlugin.swift
index 076409e..405c636 100644
--- a/packages/im_log_sdk/ios/Classes/ImLogSdkPlugin.swift
+++ b/packages/im_log_sdk/ios/Classes/ImLogSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class ImLogSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/im_log_sdk/ios/im_log_sdk.podspec b/packages/im_log_sdk/ios/im_log_sdk.podspec
index f3eb15d..8df33d7 100644
--- a/packages/im_log_sdk/ios/im_log_sdk.podspec
+++ b/packages/im_log_sdk/ios/im_log_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/im_log_sdk/macos/Classes/ImLogSdkPlugin.swift b/packages/im_log_sdk/macos/Classes/ImLogSdkPlugin.swift
index 3574fba..b00135b 100644
--- a/packages/im_log_sdk/macos/Classes/ImLogSdkPlugin.swift
+++ b/packages/im_log_sdk/macos/Classes/ImLogSdkPlugin.swift
@@ -1,5 +1,5 @@
 import Cocoa
-import FlutterMacOS
+@preconcurrency import FlutterMacOS
 
 public class ImLogSdkPlugin: NSObject, FlutterPlugin {
   public static func register(with registrar: FlutterPluginRegistrar) {
diff --git a/packages/im_log_sdk/macos/im_log_sdk.podspec b/packages/im_log_sdk/macos/im_log_sdk.podspec
index e7b420f..d864ccf 100644
--- a/packages/im_log_sdk/macos/im_log_sdk.podspec
+++ b/packages/im_log_sdk/macos/im_log_sdk.podspec
@@ -24,7 +24,7 @@ A new Flutter plugin project.
 
   s.dependency 'FlutterMacOS'
 
-  s.platform = :osx, '10.11'
+  s.platform = :osx, '14.0'
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 end
diff --git a/packages/l10n_sdk/android/build.gradle b/packages/l10n_sdk/android/build.gradle
deleted file mode 100644
index 2de5754..0000000
--- a/packages/l10n_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.l10n_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.l10n_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/l10n_sdk/android/build.gradle.kts b/packages/l10n_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..e4081dd
--- /dev/null
+++ b/packages/l10n_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.l10n_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.l10n_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/l10n_sdk/ios/Classes/L10nSdkPlugin.swift b/packages/l10n_sdk/ios/Classes/L10nSdkPlugin.swift
index 0c80a7c..eabc282 100644
--- a/packages/l10n_sdk/ios/Classes/L10nSdkPlugin.swift
+++ b/packages/l10n_sdk/ios/Classes/L10nSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class L10nSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/l10n_sdk/ios/l10n_sdk.podspec b/packages/l10n_sdk/ios/l10n_sdk.podspec
index a297469..9a1c11a 100644
--- a/packages/l10n_sdk/ios/l10n_sdk.podspec
+++ b/packages/l10n_sdk/ios/l10n_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/media_sdk/android/build.gradle b/packages/media_sdk/android/build.gradle
deleted file mode 100644
index 0ef8774..0000000
--- a/packages/media_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.media_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.media_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/media_sdk/android/build.gradle.kts b/packages/media_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..fe6f889
--- /dev/null
+++ b/packages/media_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.media_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.media_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/media_sdk/ios/Classes/MediaSdkPlugin.swift b/packages/media_sdk/ios/Classes/MediaSdkPlugin.swift
index d9b652d..49131a0 100644
--- a/packages/media_sdk/ios/Classes/MediaSdkPlugin.swift
+++ b/packages/media_sdk/ios/Classes/MediaSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class MediaSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/media_sdk/ios/media_sdk.podspec b/packages/media_sdk/ios/media_sdk.podspec
index 9125e0f..6a1e285 100644
--- a/packages/media_sdk/ios/media_sdk.podspec
+++ b/packages/media_sdk/ios/media_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/networks_sdk/android/build.gradle b/packages/networks_sdk/android/build.gradle
deleted file mode 100644
index 6746089..0000000
--- a/packages/networks_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.networks_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.networks_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/networks_sdk/android/build.gradle.kts b/packages/networks_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..bcfdb84
--- /dev/null
+++ b/packages/networks_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.networks_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.networks_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/networks_sdk/ios/Classes/NetworksSdkPlugin.swift b/packages/networks_sdk/ios/Classes/NetworksSdkPlugin.swift
index f534410..9c3a439 100644
--- a/packages/networks_sdk/ios/Classes/NetworksSdkPlugin.swift
+++ b/packages/networks_sdk/ios/Classes/NetworksSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class NetworksSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/networks_sdk/ios/networks_sdk.podspec b/packages/networks_sdk/ios/networks_sdk.podspec
index a874b54..245e3c4 100644
--- a/packages/networks_sdk/ios/networks_sdk.podspec
+++ b/packages/networks_sdk/ios/networks_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/networks_sdk/lib/networks_sdk.dart b/packages/networks_sdk/lib/networks_sdk.dart
index 3f26639..5e2405a 100644
--- a/packages/networks_sdk/lib/networks_sdk.dart
+++ b/packages/networks_sdk/lib/networks_sdk.dart
@@ -6,8 +6,9 @@ export 'src/presentation/facade/networks_messaging_api.dart';
 // Wiring - Implementations
 export 'src/presentation/wiring/networks_messaging_api_impl.dart';
 
-// Dio 类型重导出（App 层上传 / override decodeResponse 需要，避免直接依赖 dio）
-export 'package:dio/dio.dart' show FormData, MultipartFile, Response;
+// Dio 类型重导出（App 层上传 / CancelToken / override decodeResponse 需要，避免直接依赖 dio）
+export 'package:dio/dio.dart'
+    show FormData, MultipartFile, Response, CancelToken;
 
 // Config
 export 'src/presentation/wiring/api_config.dart';
@@ -18,6 +19,7 @@ export 'src/presentation/wiring/network_callbacks.dart';
 export 'src/data/dto/api_requestable.dart';
 export 'src/data/dto/api_response_wrapper.dart';
 export 'src/domain/entities/api_error.dart';
+export 'src/domain/entities/encrypted_request.dart';
 export 'src/domain/entities/http_method.dart';
 export 'src/domain/entities/api_request_type.dart';
 
diff --git a/packages/networks_sdk/lib/src/data/datasources/http/api_client.dart b/packages/networks_sdk/lib/src/data/datasources/http/api_client.dart
index fc90fdd..460934d 100644
--- a/packages/networks_sdk/lib/src/data/datasources/http/api_client.dart
+++ b/packages/networks_sdk/lib/src/data/datasources/http/api_client.dart
@@ -1,12 +1,15 @@
 import 'package:dio/dio.dart';
 import 'package:networks_sdk/src/data/datasources/http/interceptor/auth_interceptor.dart';
+import 'package:networks_sdk/src/data/datasources/http/interceptor/encryption_interceptor.dart';
 import 'package:networks_sdk/src/data/datasources/http/interceptor/logging_interceptor.dart';
 import 'package:networks_sdk/src/data/datasources/http/interceptor/retry_interceptor.dart';
 import 'package:networks_sdk/src/domain/entities/api_error.dart';
 import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
 
 /// REST API 客户端
-/// 基于 Dio，提供 `executeRequest` 唯一入口
+/// 基于 Dio，提供请求执行入口
+///
+/// 拦截器链顺序：Auth → Encryption → 自定义 → Retry → Logging
 ///
 /// 使用方式：
 /// ```dart
@@ -28,9 +31,10 @@ class ApiClient {
       receiveTimeout: const Duration(seconds: 60),
     );
 
-    // 挂载拦截器（顺序：Auth → 自定义 → Retry → Logging）
+    // 挂载拦截器（顺序：Auth → Encryption → 自定义 → Retry → Logging）
     _dio.interceptors.addAll([
       AuthInterceptor(config),
+      EncryptionInterceptor(config),
       if (additionalInterceptors != null) ...additionalInterceptors,
       RetryInterceptor(config: config, dio: _dio),
       LoggingInterceptor(onLog: config.onLog),
@@ -49,16 +53,16 @@ class ApiClient {
         return const ApiError.timeout();
       case DioExceptionType.connectionError:
         return const ApiError.noNetworkConnection();
+      case DioExceptionType.cancel:
+        return const ApiError.cancelled();
       default:
         if (e.response != null) {
           return ApiError.apiError(
             code: e.response!.statusCode ?? 0,
-            message: e.response!.statusMessage ??
-                e.message ??
-                'Request failed',
+            message: e.response!.statusMessage ?? e.message ?? 'Request failed',
           );
         }
         return ApiError.networkError(e.message ?? 'Network error');
     }
   }
-}
\ No newline at end of file
+}
diff --git a/packages/networks_sdk/lib/src/data/datasources/http/interceptor/encryption_interceptor.dart b/packages/networks_sdk/lib/src/data/datasources/http/interceptor/encryption_interceptor.dart
new file mode 100644
index 0000000..92c977f
--- /dev/null
+++ b/packages/networks_sdk/lib/src/data/datasources/http/interceptor/encryption_interceptor.dart
@@ -0,0 +1,114 @@
+import 'package:dio/dio.dart';
+import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
+
+/// 加密拦截器（预留给 cipher_guard_sdk）
+///
+/// 在拦截器链中位于 Auth 之后、Retry 之前：
+/// `Auth → Encryption → Custom → Retry → Logging`
+///
+/// 回调为 null 时自动跳过，不影响正常请求流程。
+/// 后续 cipher_guard_sdk 接入后，App 层在 ApiConfig 中注入
+/// `onEncryptRequest` / `onDecryptResponse` 即可启用加密。
+///
+/// ## 加密能力
+///
+/// 与简单的 body 加解密不同，本拦截器支持完整的请求改写：
+/// - 路径加密（如 `/api/login` → `/api/hex(encrypt(login))`）
+/// - 请求体加密（Map → base64 字符串）
+/// - Header 注入（X-Token、X-Signature、secret-key 等）
+/// - Content-Type 覆盖（application/json → text/plain）
+///
+/// 加密回调接收原始 path、headers、body，返回 [EncryptedRequest]，
+/// 拦截器根据非 null 字段覆盖请求。
+class EncryptionInterceptor extends Interceptor {
+  final ApiConfig _config;
+
+  EncryptionInterceptor(this._config);
+
+  @override
+  void onRequest(
+    RequestOptions options,
+    RequestInterceptorHandler handler,
+  ) async {
+    final encrypt = _config.onEncryptRequest;
+    if (encrypt == null) {
+      handler.next(options);
+      return;
+    }
+
+    try {
+      // 收集当前 headers（转为 Map）
+      final currentHeaders = {};
+      options.headers.forEach((key, value) {
+        if (value != null) currentHeaders[key] = value.toString();
+      });
+
+      final result = await encrypt(options.path, currentHeaders, options.data);
+
+      // 根据非 null 字段覆盖请求
+      if (result.path != null) {
+        options.path = result.path!;
+      }
+      if (result.body != null) {
+        options.data = result.body;
+      }
+      if (result.headers != null) {
+        options.headers.addAll(result.headers!);
+      }
+      if (result.contentType != null) {
+        options.contentType = result.contentType;
+      }
+
+      _config.onLog?.call(
+        'Request encrypted: ${options.path}',
+        tag: 'Encryption',
+      );
+
+      handler.next(options);
+    } catch (e) {
+      _config.onLog?.call('Request encryption failed: $e', tag: 'Encryption');
+      handler.reject(
+        DioException(
+          requestOptions: options,
+          message: 'Request encryption failed: $e',
+        ),
+      );
+    }
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) async {
+    final decrypt = _config.onDecryptResponse;
+    if (decrypt == null) {
+      handler.next(response);
+      return;
+    }
+
+    // 跳过 null 响应
+    if (response.data == null) {
+      handler.next(response);
+      return;
+    }
+
+    try {
+      final decrypted = await decrypt(response.data as Object);
+      response.data = decrypted;
+
+      _config.onLog?.call(
+        'Response decrypted: ${response.requestOptions.path}',
+        tag: 'Encryption',
+      );
+
+      handler.next(response);
+    } catch (e) {
+      _config.onLog?.call('Response decryption failed: $e', tag: 'Encryption');
+      handler.reject(
+        DioException(
+          requestOptions: response.requestOptions,
+          response: response,
+          message: 'Response decryption failed: $e',
+        ),
+      );
+    }
+  }
+}
diff --git a/packages/networks_sdk/lib/src/data/datasources/http/interceptor/retry_interceptor.dart b/packages/networks_sdk/lib/src/data/datasources/http/interceptor/retry_interceptor.dart
index 6864329..3cb5490 100644
--- a/packages/networks_sdk/lib/src/data/datasources/http/interceptor/retry_interceptor.dart
+++ b/packages/networks_sdk/lib/src/data/datasources/http/interceptor/retry_interceptor.dart
@@ -1,35 +1,41 @@
-import 'dart:async';
 import 'dart:math';
 
 import 'package:dio/dio.dart';
+import 'package:networks_sdk/src/data/datasources/http/token_refresh_manager.dart';
 import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
 
-
 /// 重试拦截器
 ///
 /// 两层重试机制：
 ///
 /// 1. **Token 刷新重试**（onResponse）
-///    检测 Token 过期响应 → 触发刷新回调 → 用新 Token 重试原请求
+///    检测 Token 过期响应 → 触发 [TokenRefreshManager] → 用新 Token 重试原请求
 ///
 /// 2. **瞬态错误重试**（onError）
 ///    5xx / 超时 / 连接失败 → 指数退避 + jitter → 自动重试
 ///    由 [ApiConfig.maxRetries] 控制（默认 0 = 不启用）
 ///
+/// 另外在 onResponse 中处理强制登出码和业务错误码。
+///
 /// 两层独立运作，可叠加。
 class RetryInterceptor extends Interceptor {
   final ApiConfig config;
   final Dio dio;
-
-  /// Token 刷新锁（防止多个请求同时刷新）
-  bool _isRefreshing = false;
-  Completer? _refreshCompleter;
+  final TokenRefreshManager _tokenManager;
 
   final _random = Random();
 
-  RetryInterceptor({required this.config, required this.dio});
+  RetryInterceptor({required this.config, required this.dio})
+    : _tokenManager = TokenRefreshManager(
+        onTokenRefresh: config.onTokenRefresh,
+        onLog: config.onLog,
+        timeout: config.tokenRefreshTimeout,
+        reuseWindow: config.tokenReuseWindow,
+        onGetTokenExpiry: config.onGetTokenExpiry,
+        proactiveRefreshThreshold: config.proactiveRefreshThreshold,
+      );
 
-  // ── Token 刷新重试 ────────────────────────────────────────────────────────
+  // ── 响应处理（Token 过期 / 强制登出 / 业务错误码）──────────────────────
 
   @override
   void onResponse(Response response, ResponseInterceptorHandler handler) {
@@ -40,13 +46,12 @@ class RetryInterceptor extends Interceptor {
 
     final data = response.data as Map;
     final code = _parseCode(data['code']);
+    final message = data['message'] as String? ?? '';
+    final requestPath = response.requestOptions.path;
 
     // 检查强制登出
     if (config.forceLogoutCodes.contains(code)) {
-      config.onLog?.call(
-        'Force logout detected (code: $code)',
-        tag: 'Network',
-      );
+      config.onLog?.call('Force logout detected (code: $code)', tag: 'Network');
       config.onForceLogout?.call();
       handler.reject(
         DioException(
@@ -58,8 +63,9 @@ class RetryInterceptor extends Interceptor {
       return;
     }
 
-    // 检查 Token 过期
-    if (config.tokenExpiredCodes.contains(code)) {
+    // 检查 Token 过期（跳过已标记为 token 重试的请求，防止递归）
+    if (config.tokenExpiredCodes.contains(code) &&
+        response.requestOptions.extra['_isTokenRetry'] != true) {
       config.onLog?.call(
         'Token expired (code: $code), refreshing...',
         tag: 'Network',
@@ -68,17 +74,27 @@ class RetryInterceptor extends Interceptor {
       return;
     }
 
+    // 业务错误码拦截：非 0 且不在特殊码集合中
+    if (code != 0 && config.onBusinessError != null) {
+      final handled = config.onBusinessError!(code, message, requestPath);
+      if (handled) {
+        // App 层已处理，正常传递响应
+        handler.next(response);
+        return;
+      }
+    }
+
     handler.next(response);
   }
 
   /// 处理 Token 过期：刷新 + 重试
   Future _handleTokenExpired(
-      Response response,
-      ResponseInterceptorHandler handler,
-      ) async {
-    final refreshSuccess = await _refreshToken();
+    Response response,
+    ResponseInterceptorHandler handler,
+  ) async {
+    final newToken = await _tokenManager.refreshIfNeeded();
 
-    if (!refreshSuccess) {
+    if (newToken == null) {
       config.onLog?.call('Token refresh failed', tag: 'Network');
       config.onForceLogout?.call();
       handler.reject(
@@ -91,12 +107,14 @@ class RetryInterceptor extends Interceptor {
       return;
     }
 
-    // 刷新成功，用新 token 重试原请求
+    // 刷新成功，更新 config 并用新 token 重试原请求
+    config.updateToken(newToken);
     config.onLog?.call('Token refreshed, retrying...', tag: 'Network');
     try {
       final options = response.requestOptions;
-      // 更新 header 中的 token
-      options.headers['token'] = config.token;
+      options.headers['token'] = newToken;
+      // 标记为 token 重试请求，防止重试后再次进入 _handleTokenExpired 造成递归
+      options.extra['_isTokenRetry'] = true;
 
       final retryResponse = await dio.fetch(options);
       handler.resolve(retryResponse);
@@ -105,41 +123,6 @@ class RetryInterceptor extends Interceptor {
     }
   }
 
-  /// Token 刷新（串行锁）
-  /// 多个请求同时过期时，只刷新一次，其余等待
-  Future _refreshToken() async {
-    if (_isRefreshing) {
-      // 等待正在进行的刷新
-      return _refreshCompleter?.future ?? Future.value(false);
-    }
-
-    _isRefreshing = true;
-    _refreshCompleter = Completer();
-
-    try {
-      if (config.onTokenRefresh == null) {
-        _refreshCompleter!.complete(false);
-        return false;
-      }
-
-      final newToken = await config.onTokenRefresh!();
-      final success = newToken != null;
-
-      if (success) {
-        config.updateToken(newToken);
-      }
-
-      _refreshCompleter!.complete(success);
-      return success;
-    } catch (e) {
-      _refreshCompleter!.complete(false);
-      return false;
-    } finally {
-      _isRefreshing = false;
-      _refreshCompleter = null;
-    }
-  }
-
   // ── 瞬态错误重试（指数退避 + jitter）────────────────────────────────────
 
   @override
@@ -162,7 +145,7 @@ class RetryInterceptor extends Interceptor {
     final delayMs = _backoffDelay(attempt);
     config.onLog?.call(
       'Transient error, retry ${attempt + 1}/${config.maxRetries} '
-          'in ${delayMs}ms: ${options.path}',
+      'in ${delayMs}ms: ${options.path}',
       tag: 'Retry',
     );
 
@@ -184,7 +167,7 @@ class RetryInterceptor extends Interceptor {
       case DioExceptionType.connectionError:
         return true;
       case DioExceptionType.badResponse:
-      // 5xx 服务端错误可重试
+        // 5xx 服务端错误可重试
         final statusCode = err.response?.statusCode;
         return statusCode != null && statusCode >= 500;
       default:
@@ -198,7 +181,9 @@ class RetryInterceptor extends Interceptor {
   int _backoffDelay(int attempt) {
     final baseMs = config.retryBaseDelay.inMilliseconds;
     final exponentialMs = min(baseMs * pow(2, attempt).toInt(), 30000);
-    final jitterMs = _random.nextInt((exponentialMs * 0.25).toInt().clamp(1, 7500));
+    final jitterMs = _random.nextInt(
+      (exponentialMs * 0.25).toInt().clamp(1, 7500),
+    );
     return exponentialMs + jitterMs;
   }
 
diff --git a/packages/networks_sdk/lib/src/data/datasources/http/token_refresh_manager.dart b/packages/networks_sdk/lib/src/data/datasources/http/token_refresh_manager.dart
new file mode 100644
index 0000000..96bee72
--- /dev/null
+++ b/packages/networks_sdk/lib/src/data/datasources/http/token_refresh_manager.dart
@@ -0,0 +1,152 @@
+import 'dart:async';
+
+import 'package:networks_sdk/src/presentation/wiring/network_callbacks.dart';
+
+/// Token 刷新管理器
+///
+/// 两种刷新模式：
+///
+/// 1. **被动刷新**（[refreshIfNeeded]）— 拦截器检测到 token 过期后调用
+/// 2. **主动刷新**（[proactivelyRefreshIfNeeded]）— 解析 JWT exp，
+///    距过期不足阈值时提前刷新，避免带过期 token 发请求
+///
+/// 两种模式共享串行锁和时间窗口保护：
+/// - **串行锁** — 同一时刻只执行一次刷新，其余请求等待同一 Completer
+/// - **时间窗口** — 刷新成功后 [reuseWindow] 内再次调用直接返回缓存 token
+/// - **超时保护** — 刷新回调超过 [timeout] 自动失败，防止死锁
+class TokenRefreshManager {
+  final OnTokenRefresh? onTokenRefresh;
+  final OnLog? onLog;
+
+  /// 刷新超时时间（防止 onTokenRefresh 卡住导致所有请求阻塞）
+  final Duration timeout;
+
+  /// 时间窗口：刷新成功后此时间内再次调用直接返回缓存 token
+  final Duration reuseWindow;
+
+  /// Token 过期时间解析（App 层注入 JWT exp 解析逻辑）
+  final OnGetTokenExpiry? onGetTokenExpiry;
+
+  /// 主动刷新阈值：距过期不足此时间时提前刷新（默认 1 小时）
+  final Duration proactiveRefreshThreshold;
+
+  /// 当前正在进行的刷新任务（null = 空闲）
+  Completer? _completer;
+
+  /// 上次刷新成功的时间戳
+  DateTime? _lastRefreshTime;
+
+  /// 上次刷新成功的 token（时间窗口内复用）
+  String? _lastToken;
+
+  TokenRefreshManager({
+    this.onTokenRefresh,
+    this.onLog,
+    this.timeout = const Duration(seconds: 10),
+    this.reuseWindow = const Duration(seconds: 3),
+    this.onGetTokenExpiry,
+    this.proactiveRefreshThreshold = const Duration(hours: 1),
+  });
+
+  /// 执行 token 刷新（如果需要）
+  ///
+  /// 返回新 token（刷新成功或在时间窗口内），
+  /// 返回 null = 刷新失败或超时。
+  Future refreshIfNeeded() async {
+    // 1. 时间窗口：最近刷新过且未超时 → 直接返回缓存的 token
+    if (_isWithinReuseWindow()) {
+      _log('Token refreshed recently, reusing');
+      return _lastToken;
+    }
+
+    // 2. 有正在进行的刷新 → 等待同一 Completer
+    final existing = _completer;
+    if (existing != null) {
+      _log('Waiting for ongoing token refresh');
+      return existing.future;
+    }
+
+    // 3. 发起新的刷新
+    if (onTokenRefresh == null) {
+      _log('No onTokenRefresh callback configured');
+      return null;
+    }
+
+    final completer = Completer();
+    _completer = completer;
+
+    try {
+      final newToken = await onTokenRefresh!().timeout(
+        timeout,
+        onTimeout: () {
+          _log('Token refresh timed out after ${timeout.inSeconds}s');
+          return null;
+        },
+      );
+
+      final success = newToken != null && newToken.isNotEmpty;
+
+      if (success) {
+        _lastRefreshTime = DateTime.now();
+        _lastToken = newToken;
+        _log('Token refreshed successfully');
+      } else {
+        _log('Token refresh failed (null or empty token)');
+      }
+
+      // 先 complete 再清引用，确保等待者能拿到结果
+      completer.complete(success ? newToken : null);
+      return success ? newToken : null;
+    } catch (e) {
+      _log('Token refresh error: $e');
+      completer.complete(null);
+      return null;
+    } finally {
+      // 清理引用（Completer 已 complete，等待者不受影响）
+      _completer = null;
+    }
+  }
+
+  /// 检查 token 是否即将过期，是则主动刷新
+  ///
+  /// 解析 [currentToken] 的过期时间，距过期不足 [proactiveRefreshThreshold]
+  /// 时调用 [refreshIfNeeded] 刷新。复用串行锁和超时保护。
+  ///
+  /// 返回新 token（已刷新）或 null（不需要刷新 / 刷新失败 / 无法解析过期时间）。
+  Future proactivelyRefreshIfNeeded(String? currentToken) async {
+    if (currentToken == null || onGetTokenExpiry == null) return null;
+
+    final expiry = onGetTokenExpiry!(currentToken);
+    if (expiry == null) return null;
+
+    final remaining = expiry.difference(DateTime.now());
+    if (remaining > proactiveRefreshThreshold) {
+      _log(
+        'Token valid (expires in ${remaining.inMinutes}min), skip proactive refresh',
+      );
+      return null;
+    }
+
+    _log(
+      'Token expiring soon (${remaining.inMinutes}min left), proactively refreshing',
+    );
+    return refreshIfNeeded();
+  }
+
+  /// 重置状态（登出时调用）
+  void reset() {
+    _lastRefreshTime = null;
+    _lastToken = null;
+    // 不清理 _completer，让正在等待的请求正常结束
+  }
+
+  bool _isWithinReuseWindow() {
+    final lastTime = _lastRefreshTime;
+    if (lastTime == null) return false;
+    return DateTime.now().difference(lastTime) < reuseWindow;
+  }
+
+  void _log(String message) {
+    onLog?.call(message, tag: 'TokenRefresh');
+  }
+}
diff --git a/packages/networks_sdk/lib/src/data/datasources/networks_sdk_method_channel_datasource.dart b/packages/networks_sdk/lib/src/data/datasources/networks_sdk_method_channel_datasource.dart
index 9e8a418..80490b8 100644
--- a/packages/networks_sdk/lib/src/data/datasources/networks_sdk_method_channel_datasource.dart
+++ b/packages/networks_sdk/lib/src/data/datasources/networks_sdk_method_channel_datasource.dart
@@ -1,14 +1,25 @@
+import 'dart:io';
+
 import 'package:dio/dio.dart';
 import 'package:networks_sdk/src/data/datasources/http/api_client.dart';
 import 'package:networks_sdk/src/data/dto/api_requestable.dart';
 import 'package:networks_sdk/src/domain/entities/api_error.dart';
 import 'package:networks_sdk/src/domain/entities/api_request_type.dart';
 import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
+import 'package:networks_sdk/src/presentation/wiring/network_callbacks.dart';
 import '../../../networks_sdk_platform_interface.dart';
 import '../../domain/entities/http_method.dart';
 
-class NetworksSdkMethodChannelDataSource 
-{
+/// 网络层数据源
+///
+/// 封装 [ApiClient]，提供两种请求入口：
+/// - [executeRequest] — 统一请求入口（标准 / Upload / 流式）
+/// - [executeDownload] — 带进度的文件下载（支持断点续传）
+///
+/// 流式（SSE）请求也走 [executeRequest]，由业务 Request 类 override
+/// `decodeResponse` 处理 SSE 解析。SDK 内部根据
+/// `requestType == ApiRequestType.stream` 自动切换 `ResponseType.plain`。
+class NetworksSdkMethodChannelDataSource {
   final NetworksSdkPlatform platform;
 
   late ApiClient apiClient;
@@ -16,44 +27,51 @@ class NetworksSdkMethodChannelDataSource
   NetworksSdkMethodChannelDataSource(this.platform);
 
   Future getPlatformVersion() async {
-    return await getPlatformVersion();
+    return await platform.getPlatformVersion();
   }
 
-  void initialize(ApiConfig apiConfig){
+  void initialize(ApiConfig apiConfig) {
     apiClient = ApiClient(config: apiConfig);
   }
 
-  /// 执行 API 请求 — 唯一入口
+  // ══════════════════════════════════════════════════════════════════════════
+  //  统一请求入口
+  // ══════════════════════════════════════════════════════════════════════════
+
+  /// 执行 API 请求 — 统一入口
   ///
-  /// 流程：网络前置检查 → 构建 URL → 设置元数据 → 执行请求 → 解码响应 → 错误映射
-  /// 拦截器负责：header 注入、Token 刷新重试、日志
+  /// 支持三种请求类型，由 `request.requestType` 控制行为：
+  /// - `request` / `login` — 标准 JSON 请求
+  /// - `upload` — 文件上传（FormData / 二进制）
+  /// - `stream` — SSE / chunked，内部用 `ResponseType.plain` 获取原始文本，
+  ///   由业务 Request 类 override `decodeResponse` 处理 SSE 解析
+  ///
+  /// 流程：网络前置检查 → 构建 URL → 设置元数据 → 执行请求
+  /// → 响应变换（可选，stream 类型跳过）→ 解码响应 → 错误映射
+  ///
+  /// 拦截器负责：header 注入、加密/解密、Token 刷新重试、业务错误拦截、日志
   ///
   /// Upload 类型支持两种模式：
   /// - 自有后端上传：path 为相对路径，自动拼接 baseURL
   /// - S3 presigned URL：path 以 http 开头，直接使用全路径
-  Future executeRequest(ApiRequestable request) async {
-    // 前置检查：网络不可用时直接抛错，避免无效请求
-    if (apiClient.config.onCheckNetworkAvailable != null) {
-      final available = await apiClient.config.onCheckNetworkAvailable!();
-      if (!available) {
-        apiClient.config.onLog?.call(
-          'Network unavailable, abort request: ${request.path}',
-          tag: 'ApiClient',
-        );
-        throw const ApiError.noNetworkConnection();
-      }
-    }
+  Future executeRequest(
+    ApiRequestable request, {
+    CancelToken? cancelToken,
+  }) async {
+    await _checkNetwork(request.path);
 
     try {
-      // Upload 且 path 以 http 开头 → 直接用全路径（S3 presigned URL）
-      // 否则 → 拼接 baseURL
       final isUpload = request.requestType == ApiRequestType.upload;
+      final isStream = request.requestType == ApiRequestType.stream;
       final path = request.path;
-      final url = (isUpload && path.startsWith('http')) ? path : '${apiClient.config.baseURL}$path';
+      final url = (isUpload && path.startsWith('http'))
+          ? path
+          : '${apiClient.config.baseURL}$path';
 
-      // 将请求元数据写入 extra，供拦截器读取
       final options = Options(
         method: request.method.value,
+        // 流式请求用 plain，Dio 返回原始文本，由 decodeResponse 解析 SSE
+        responseType: isStream ? ResponseType.plain : null,
         extra: {
           'requestType': request.requestType,
           'includeToken': request.includeToken,
@@ -62,19 +80,22 @@ class NetworksSdkMethodChannelDataSource
       );
 
       // 访问 parameters 触发代码生成器的 fromJson 注册
-      // （@ApiRequest 生成的 mixin 在 parameters getter 中注册响应类型）
       final params = request.parameters;
 
-      // GET → queryParameters；POST/PUT/DELETE/PATCH → JSON body；Upload → uploadData
       final isGet = request.method == HttpMethod.get;
       final response = await apiClient.dio.request(
         url,
         data: isUpload ? request.uploadData : (isGet ? null : params),
         queryParameters: isGet ? params : null,
         options: options,
+        cancelToken: cancelToken,
       );
 
-      // 解码响应（Upload 类型通常需要 override decodeResponse）
+      // 响应变换：stream 类型由 decodeResponse 自行处理，不做变换
+      if (!isStream) {
+        _applyResponseTransform(response);
+      }
+
       return request.decodeResponse(response);
     } on DioException catch (e) {
       throw apiClient.mapDioError(e);
@@ -85,4 +106,162 @@ class NetworksSdkMethodChannelDataSource
     }
   }
 
+  // ══════════════════════════════════════════════════════════════════════════
+  //  文件下载
+  // ══════════════════════════════════════════════════════════════════════════
+
+  /// 下载文件到本地路径
+  ///
+  /// 支持进度回调和断点续传（通过 HTTP Range header 实现）。
+  ///
+  /// 非续传模式直接用 Dio.download（高效，内部流式写入）。
+  /// 续传模式用 stream + FileMode.append，因为 Dio.download 始终从
+  /// 文件头部写入，无法正确追加到已下载部分之后。
+  ///
+  /// [url] — 下载 URL（完整路径或相对路径，相对路径自动拼接 baseURL）
+  /// [savePath] — 本地保存路径
+  /// [onProgress] — 下载进度回调
+  /// [cancelToken] — 取消令牌
+  /// [resume] — 是否断点续传（文件已存在时从断点继续下载）
+  /// [headers] — 额外请求头
+  Future executeDownload({
+    required String url,
+    required String savePath,
+    OnDownloadProgress? onProgress,
+    CancelToken? cancelToken,
+    bool resume = false,
+    Map? headers,
+  }) async {
+    await _checkNetwork(url);
+
+    try {
+      final fullUrl = url.startsWith('http')
+          ? url
+          : '${apiClient.config.baseURL}$url';
+
+      final extraHeaders = {};
+      if (headers != null) extraHeaders.addAll(headers);
+
+      // 断点续传：读取已下载部分的大小，设置 Range header
+      int startBytes = 0;
+      if (resume) {
+        final file = File(savePath);
+        if (file.existsSync()) {
+          startBytes = file.lengthSync();
+          extraHeaders['Range'] = 'bytes=$startBytes-';
+        }
+      }
+
+      if (resume && startBytes > 0) {
+        // 续传模式：stream + append，确保新数据追加到文件末尾
+        await _downloadWithResume(
+          url: fullUrl,
+          savePath: savePath,
+          startBytes: startBytes,
+          headers: extraHeaders,
+          onProgress: onProgress,
+          cancelToken: cancelToken,
+        );
+      } else {
+        // 普通下载：Dio.download（高效，内部流式写入）
+        await apiClient.dio.download(
+          fullUrl,
+          savePath,
+          cancelToken: cancelToken,
+          deleteOnError: true,
+          options: Options(
+            headers: extraHeaders.isEmpty ? null : extraHeaders,
+            extra: {
+              'requestType': ApiRequestType.download,
+              'includeToken': true,
+            },
+          ),
+          onReceiveProgress: onProgress != null
+              ? (received, total) => onProgress(received, total)
+              : null,
+        );
+      }
+    } on DioException catch (e) {
+      throw apiClient.mapDioError(e);
+    } on ApiError {
+      rethrow;
+    } catch (e) {
+      throw ApiError.unknown(e.toString());
+    }
+  }
+
+  /// 断点续传下载：stream 响应 + FileMode.append
+  ///
+  /// Dio.download 内部用 FileMode.write（从头覆盖），无法正确续传。
+  /// 这里手动读流并追加写入文件。
+  Future _downloadWithResume({
+    required String url,
+    required String savePath,
+    required int startBytes,
+    required Map headers,
+    OnDownloadProgress? onProgress,
+    CancelToken? cancelToken,
+  }) async {
+    final response = await apiClient.dio.get(
+      url,
+      cancelToken: cancelToken,
+      options: Options(
+        responseType: ResponseType.stream,
+        headers: headers.isEmpty ? null : headers,
+        extra: {'requestType': ApiRequestType.download, 'includeToken': true},
+      ),
+    );
+
+    final stream = response.data?.stream;
+    if (stream == null) return;
+
+    // Content-Length 是本次传输量（不含已下载部分）
+    final contentLength =
+        int.tryParse(response.headers.value('content-length') ?? '') ?? -1;
+    final totalBytes = contentLength > 0 ? contentLength + startBytes : -1;
+
+    final file = File(savePath);
+    final raf = file.openSync(mode: FileMode.writeOnlyAppend);
+    int received = startBytes;
+
+    try {
+      await for (final chunk in stream) {
+        raf.writeFromSync(chunk);
+        received += chunk.length;
+        onProgress?.call(received, totalBytes);
+      }
+    } finally {
+      raf.closeSync();
+    }
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════
+  //  内部辅助
+  // ══════════════════════════════════════════════════════════════════════════
+
+  /// 网络前置检查，不可用时直接抛 [ApiError.noNetworkConnection]
+  Future _checkNetwork(String path) async {
+    if (apiClient.config.onCheckNetworkAvailable != null) {
+      final available = await apiClient.config.onCheckNetworkAvailable!();
+      if (!available) {
+        apiClient.config.onLog?.call(
+          'Network unavailable, abort request: $path',
+          tag: 'ApiClient',
+        );
+        throw const ApiError.noNetworkConnection();
+      }
+    }
+  }
+
+  /// 应用响应变换（如果 App 层注入了 onTransformResponse）
+  void _applyResponseTransform(Response response) {
+    final transform = apiClient.config.onTransformResponse;
+    if (transform == null) return;
+    if (response.data is! Map) return;
+
+    final transformed = transform(response.data as Map);
+    if (transformed != null) {
+      response.data = transformed;
+    }
+  }
 }
diff --git a/packages/networks_sdk/lib/src/data/datasources/socket/socket_client.dart b/packages/networks_sdk/lib/src/data/datasources/socket/socket_client.dart
index 84f47d0..a84b856 100644
--- a/packages/networks_sdk/lib/src/data/datasources/socket/socket_client.dart
+++ b/packages/networks_sdk/lib/src/data/datasources/socket/socket_client.dart
@@ -1,6 +1,8 @@
 import 'dart:async';
 import 'dart:convert';
+import 'dart:io' as io;
 import 'dart:math';
+import 'dart:typed_data';
 
 import 'package:networks_sdk/networks_sdk.dart';
 import 'package:web_socket_channel/io.dart';
@@ -9,10 +11,12 @@ import 'package:web_socket_channel/web_socket_channel.dart';
 /// WebSocket 长连接客户端
 ///
 /// 提供：
-/// - 连接 / 断连 / 自动重连（指数退避）
+/// - 连接 / 断连 / 自动重连（指数退避，支持无限重连）
 /// - 双层心跳（底层 ping + 应用层 heartbeat）
-/// - Stream 输出（消息、连接状态、错误）
+/// - Stream 输出（JSON 消息、原始字符串、二进制、连接状态、错误）
 /// - 生命周期感知（前后台切换）
+/// - Token 热更新（不断连）
+/// - 消息加密/解密钩子（预留给 cipher_guard_sdk）
 ///
 /// ## 使用方式
 ///
@@ -28,6 +32,9 @@ import 'package:web_socket_channel/web_socket_channel.dart';
 /// // 发消息
 /// await client.send({'type': 'chat', 'data': {...}});
 ///
+/// // Token 热更新（不断连，下次重连自动使用新 token）
+/// client.updateToken('new_token');
+///
 /// // 断连
 /// await client.disconnect();
 /// ```
@@ -56,8 +63,9 @@ class SocketClient {
   // ── Stream Controllers ──
   final _messageController = StreamController>.broadcast();
   final _rawMessageController = StreamController.broadcast();
+  final _binaryMessageController = StreamController.broadcast();
   final _connectionStateController =
-  StreamController.broadcast();
+      StreamController.broadcast();
   final _errorController = StreamController.broadcast();
 
   SocketClient({required this.config});
@@ -93,12 +101,20 @@ class SocketClient {
   }
 
   /// 当前是否已连接
-  bool get isConnected =>
-      _connectionState == SocketConnectionState.connected;
+  bool get isConnected => _connectionState == SocketConnectionState.connected;
 
   /// 当前连接状态
   SocketConnectionState get connectionState => _connectionState;
 
+  /// Token 热更新（不断开连接）
+  ///
+  /// 仅更新内部持有的 token，下次重连时自动使用新 token。
+  /// 适用于 token 刷新后同步到 WebSocket 的场景。
+  void updateToken(String token) {
+    _currentToken = token;
+    _log('Token updated (no reconnect)');
+  }
+
   // ══════════════════════════════════════════════════════════════════════════
   //  公开 API — 发送
   // ══════════════════════════════════════════════════════════════════════════
@@ -109,6 +125,8 @@ class SocketClient {
   }
 
   /// 发送原始字符串
+  ///
+  /// 如果配置了 [SocketConfig.onEncryptMessage]，发送前自动加密。
   Future sendString(String message) async {
     if (!isConnected || _channel == null) {
       _emitError(SocketError.sendFailed('Not connected'));
@@ -116,7 +134,27 @@ class SocketClient {
     }
 
     try {
-      _channel!.sink.add(message);
+      String payload = message;
+      if (config.onEncryptMessage != null) {
+        payload = await config.onEncryptMessage!(message);
+      }
+      _channel!.sink.add(payload);
+      return true;
+    } catch (e) {
+      _emitError(SocketError.sendFailed(e.toString()));
+      return false;
+    }
+  }
+
+  /// 发送二进制数据
+  Future sendBytes(List bytes) async {
+    if (!isConnected || _channel == null) {
+      _emitError(SocketError.sendFailed('Not connected'));
+      return false;
+    }
+
+    try {
+      _channel!.sink.add(bytes);
       return true;
     } catch (e) {
       _emitError(SocketError.sendFailed(e.toString()));
@@ -134,6 +172,9 @@ class SocketClient {
   /// 原始字符串消息流（JSON 解析失败的也走这里）
   Stream get rawMessageStream => _rawMessageController.stream;
 
+  /// 二进制消息流
+  Stream get binaryMessageStream => _binaryMessageController.stream;
+
   /// 连接状态变化流
   Stream get connectionStateStream =>
       _connectionStateController.stream;
@@ -171,6 +212,7 @@ class SocketClient {
     await _doDisconnect(reason: 'Dispose');
     await _messageController.close();
     await _rawMessageController.close();
+    await _binaryMessageController.close();
     await _connectionStateController.close();
     await _errorController.close();
   }
@@ -197,24 +239,36 @@ class SocketClient {
     _log('Connecting to $url');
 
     try {
-      // 构建最终 URL（拼接 token）
-      final connectUri = _currentToken != null
-          ? uri.replace(
-        queryParameters: {
-          ...uri.queryParameters,
-          'token': _currentToken!,
-        },
-      )
-          : uri;
+      // 构建最终连接 URL
+      //
+      // 有 onBuildConnectUrl 回调时，App 层完全控制 URL（路径加密、
+      // token 加密、添加 cipher 参数等）。
+      // 无回调时使用默认行为：URL 后追加 ?token=xxx。
+      final String connectUrlString;
 
-      // 创建 WebSocket 连接
-      _channel = IOWebSocketChannel.connect(
-        connectUri,
-        pingInterval: config.pingInterval,
-      );
+      if (config.onBuildConnectUrl != null) {
+        connectUrlString = config.onBuildConnectUrl!(url, _currentToken);
+      } else {
+        final connectUri = _currentToken != null
+            ? uri.replace(
+                queryParameters: {
+                  ...uri.queryParameters,
+                  'token': _currentToken!,
+                },
+              )
+            : uri;
+        connectUrlString = connectUri.toString();
+      }
 
-      // 等待连接就绪
-      await _channel!.ready.timeout(config.connectTimeout);
+      // 创建 WebSocket 连接（通过 dart:io 支持压缩选项）
+      final rawSocket = await io.WebSocket.connect(
+        connectUrlString,
+        compression: config.enableCompression
+            ? io.CompressionOptions.compressionDefault
+            : io.CompressionOptions.compressionOff,
+      ).timeout(config.connectTimeout);
+      rawSocket.pingInterval = config.pingInterval;
+      _channel = IOWebSocketChannel(rawSocket);
 
       _log('Connected');
       _updateConnectionState(SocketConnectionState.connected);
@@ -270,26 +324,45 @@ class SocketClient {
   //  内部 — 消息处理
   // ══════════════════════════════════════════════════════════════════════════
 
-  void _handleMessage(dynamic data) {
+  void _handleMessage(dynamic data) async {
+    // 二进制消息
+    if (data is List) {
+      _binaryMessageController.add(
+        data is Uint8List ? data : Uint8List.fromList(data),
+      );
+      return;
+    }
+
     if (data is! String) {
-      // 非字符串消息（如二进制），走 rawMessageStream
       _rawMessageController.add(data.toString());
       return;
     }
 
-    // 检查 pong 心跳回复
-    if (data == 'pong') {
+    // 解密（如果配置了解密回调）
+    String text = data;
+    if (config.onDecryptMessage != null) {
+      try {
+        text = await config.onDecryptMessage!(data);
+      } catch (e) {
+        _log('Message decryption failed: $e');
+        _rawMessageController.add(data);
+        return;
+      }
+    }
+
+    // 检查 pong 心跳回复（解密后检查，加密场景下也能正确匹配）
+    if (text == 'pong') {
       _onPongReceived();
       return;
     }
 
     // 尝试 JSON 解析
     try {
-      final json = jsonDecode(data) as Map;
+      final json = jsonDecode(text) as Map;
       _messageController.add(json);
     } catch (_) {
       // JSON 解析失败，走原始消息流
-      _rawMessageController.add(data);
+      _rawMessageController.add(text);
     }
   }
 
@@ -328,11 +401,21 @@ class SocketClient {
     _waitingForPong = false;
   }
 
-  void _sendPing() {
+  void _sendPing() async {
     if (_waitingForPong) return;
 
     _waitingForPong = true;
-    _channel?.sink.add('ping');
+
+    // 加密场景下 ping 也要加密，与 pong 解密对称
+    String pingPayload = 'ping';
+    if (config.onEncryptMessage != null) {
+      try {
+        pingPayload = await config.onEncryptMessage!('ping');
+      } catch (e) {
+        _log('Ping encryption failed: $e');
+      }
+    }
+    _channel?.sink.add(pingPayload);
 
     // 启动 pong 超时计时器
     _pongTimeoutTimer = Timer(config.pongTimeout, () {
@@ -360,7 +443,9 @@ class SocketClient {
     if (_manualDisconnect || !config.autoReconnect || _isBackground) return;
     if (_connectionState == SocketConnectionState.reconnecting) return;
 
-    if (_reconnectAttempts >= config.maxReconnectAttempts) {
+    // 非无限重连模式下检查重连次数上限
+    if (!config.unlimitedReconnect &&
+        _reconnectAttempts >= config.maxReconnectAttempts) {
       _log('Max reconnect attempts reached ($_reconnectAttempts)');
       _reconnectAttempts = 0;
       return;
@@ -375,11 +460,16 @@ class SocketClient {
       pow(2, _reconnectAttempts).toInt() * 1000,
       config.maxReconnectDelay.inMilliseconds,
     );
-    final jitterMs = _random.nextInt((baseDelayMs * 0.25).toInt().clamp(1, 7500));
+    final jitterMs = _random.nextInt(
+      (baseDelayMs * 0.25).toInt().clamp(1, 7500),
+    );
     final delay = Duration(milliseconds: baseDelayMs + jitterMs);
 
-    _log('Reconnecting in ${delay.inMilliseconds}ms '
-        '(attempt $_reconnectAttempts/${config.maxReconnectAttempts})');
+    final attemptsInfo = config.unlimitedReconnect
+        ? 'attempt $_reconnectAttempts/unlimited'
+        : 'attempt $_reconnectAttempts/${config.maxReconnectAttempts}';
+
+    _log('Reconnecting in ${delay.inMilliseconds}ms ($attemptsInfo)');
 
     _reconnectTimer = Timer(delay, () async {
       // 重连前检查网络
@@ -393,6 +483,17 @@ class SocketClient {
         }
       }
 
+      // 重连前回调（App 层刷新即将过期的 token 等）
+      if (config.onBeforeReconnect != null) {
+        try {
+          await config.onBeforeReconnect!();
+        } catch (e) {
+          _log('onBeforeReconnect failed: $e, skip this reconnect');
+          _startReconnect();
+          return;
+        }
+      }
+
       _doConnect();
     });
   }
diff --git a/packages/networks_sdk/lib/src/data/repositories/networks_messaging_repository_impl.dart b/packages/networks_sdk/lib/src/data/repositories/networks_messaging_repository_impl.dart
index 9069565..8663c42 100644
--- a/packages/networks_sdk/lib/src/data/repositories/networks_messaging_repository_impl.dart
+++ b/packages/networks_sdk/lib/src/data/repositories/networks_messaging_repository_impl.dart
@@ -1,10 +1,12 @@
+import 'dart:typed_data';
+
 import 'package:networks_sdk/src/data/datasources/socket/socket_client.dart';
 import 'package:networks_sdk/src/domain/entities/socket_connection_state.dart';
 import 'package:networks_sdk/src/domain/entities/socket_error.dart';
 import 'package:networks_sdk/src/domain/repositories/networks_messaging_repository.dart';
 import 'package:networks_sdk/src/presentation/wiring/socket_config.dart';
 
-/// Messaging Repository Implementation (Data)
+/// [NetworksMessagingRepository] 的实现，透传给 [SocketClient]
 class NetworksMessagingRepositoryImpl implements NetworksMessagingRepository {
   SocketClient? _socketClient;
   bool _isInitialized = false;
@@ -47,6 +49,12 @@ class NetworksMessagingRepositoryImpl implements NetworksMessagingRepository {
     return _socketClient!.connectionState;
   }
 
+  @override
+  void updateToken(String token) {
+    _checkInitialized();
+    _socketClient!.updateToken(token);
+  }
+
   @override
   Future send(Map message) {
     _checkInitialized();
@@ -59,6 +67,12 @@ class NetworksMessagingRepositoryImpl implements NetworksMessagingRepository {
     return _socketClient!.sendString(message);
   }
 
+  @override
+  Future sendBytes(List bytes) {
+    _checkInitialized();
+    return _socketClient!.sendBytes(bytes);
+  }
+
   @override
   Stream> get messageStream {
     _checkInitialized();
@@ -71,6 +85,12 @@ class NetworksMessagingRepositoryImpl implements NetworksMessagingRepository {
     return _socketClient!.rawMessageStream;
   }
 
+  @override
+  Stream get binaryMessageStream {
+    _checkInitialized();
+    return _socketClient!.binaryMessageStream;
+  }
+
   @override
   Stream get connectionStateStream {
     _checkInitialized();
@@ -104,4 +124,3 @@ class NetworksMessagingRepositoryImpl implements NetworksMessagingRepository {
     _isInitialized = false;
   }
 }
-
diff --git a/packages/networks_sdk/lib/src/data/repositories/networks_sdk_repository_impl.dart b/packages/networks_sdk/lib/src/data/repositories/networks_sdk_repository_impl.dart
index a9d6318..b255647 100644
--- a/packages/networks_sdk/lib/src/data/repositories/networks_sdk_repository_impl.dart
+++ b/packages/networks_sdk/lib/src/data/repositories/networks_sdk_repository_impl.dart
@@ -1,13 +1,15 @@
-//Repository Impl
+// Repository Impl
 
+import 'package:dio/dio.dart';
 import 'package:networks_sdk/src/data/dto/api_requestable.dart';
 import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
+import 'package:networks_sdk/src/presentation/wiring/network_callbacks.dart';
 
 import '../../domain/repositories/networks_sdk_repository.dart';
 import '../datasources/networks_sdk_method_channel_datasource.dart';
 
-class NetworksSdkRepositoryImpl implements NetworksSdkRepository
-{
+/// [NetworksSdkRepository] 的实现，透传给 [NetworksSdkMethodChannelDataSource]
+class NetworksSdkRepositoryImpl implements NetworksSdkRepository {
   final NetworksSdkMethodChannelDataSource _datasource;
 
   const NetworksSdkRepositoryImpl(this._datasource);
@@ -18,12 +20,34 @@ class NetworksSdkRepositoryImpl implements NetworksSdkRepository
   }
 
   @override
-  void initialize(ApiConfig apiConfig){
-     _datasource.initialize(apiConfig);
+  void initialize(ApiConfig apiConfig) {
+    _datasource.initialize(apiConfig);
   }
 
   @override
-  Future executeRequest(ApiRequestable request) {
-    return _datasource.executeRequest(request);
+  Future executeRequest(
+    ApiRequestable request, {
+    CancelToken? cancelToken,
+  }) {
+    return _datasource.executeRequest(request, cancelToken: cancelToken);
+  }
+
+  @override
+  Future executeDownload({
+    required String url,
+    required String savePath,
+    OnDownloadProgress? onProgress,
+    CancelToken? cancelToken,
+    bool resume = false,
+    Map? headers,
+  }) {
+    return _datasource.executeDownload(
+      url: url,
+      savePath: savePath,
+      onProgress: onProgress,
+      cancelToken: cancelToken,
+      resume: resume,
+      headers: headers,
+    );
   }
 }
diff --git a/packages/networks_sdk/lib/src/domain/entities/api_error.dart b/packages/networks_sdk/lib/src/domain/entities/api_error.dart
index 302c39e..f8beca3 100644
--- a/packages/networks_sdk/lib/src/domain/entities/api_error.dart
+++ b/packages/networks_sdk/lib/src/domain/entities/api_error.dart
@@ -13,6 +13,9 @@ class ApiError with _$ApiError implements Exception {
     required int code,
     required String message,
   }) = _ApiError;
+
+  /// 请求被 CancelToken 取消
+  const factory ApiError.cancelled() = _Cancelled;
   const factory ApiError.unknown(String? message) = _Unknown;
 }
 
@@ -25,7 +28,8 @@ extension ApiErrorExtension on ApiError {
       networkError: (message) => 'Network error: $message',
       decodingError: (message) => 'Decoding error: $message',
       apiError: (code, message) => message,
+      cancelled: () => 'Request cancelled',
       unknown: (message) => message ?? 'Unknown error',
     );
   }
-}
\ No newline at end of file
+}
diff --git a/packages/networks_sdk/lib/src/domain/entities/api_request_type.dart b/packages/networks_sdk/lib/src/domain/entities/api_request_type.dart
index dd41078..864c07e 100644
--- a/packages/networks_sdk/lib/src/domain/entities/api_request_type.dart
+++ b/packages/networks_sdk/lib/src/domain/entities/api_request_type.dart
@@ -8,4 +8,13 @@ enum ApiRequestType {
 
   /// 文件上传（multipart，不序列化 parameters）
   upload,
+
+  /// 流式请求（SSE / chunked）
+  ///
+  /// SDK 内部自动切换 `ResponseType.plain`，Dio 返回原始文本。
+  /// 业务 Request 类 override `decodeResponse` 处理 SSE 解析。
+  stream,
+
+  /// 文件下载（带进度回调，支持断点续传）
+  download,
 }
diff --git a/packages/networks_sdk/lib/src/domain/entities/encrypted_request.dart b/packages/networks_sdk/lib/src/domain/entities/encrypted_request.dart
new file mode 100644
index 0000000..595185d
--- /dev/null
+++ b/packages/networks_sdk/lib/src/domain/entities/encrypted_request.dart
@@ -0,0 +1,55 @@
+/// HTTP 请求加密结果
+///
+/// 加密回调返回此对象，[EncryptionInterceptor] 根据非 null 字段覆盖原始请求。
+/// 未设置的字段保持原值不变。
+///
+/// 设计依据：HTTP 加密模式下，加密后需要同时修改：
+/// - 路径（原文 path 加密为 hex 编码）
+/// - 请求体（JSON body 加密为 base64 字符串，不再是 Map）
+/// - Headers（添加 X-Token、X-Signature、secret-key 等加密 header）
+/// - Content-Type（JSON → text/plain）
+///
+/// ```dart
+/// // 加密回调返回示例
+/// EncryptedRequest(
+///   path: '/api/${hexEncode(encrypt(originalPath))}',
+///   body: base64Encode(encrypt(jsonBody)),
+///   headers: {
+///     'X-Token': encryptedToken,
+///     'X-Signature': signature,
+///     'secret-key': clientPublicKey,
+///   },
+///   contentType: 'text/plain',
+/// )
+/// ```
+class EncryptedRequest {
+  /// 加密后的路径
+  ///
+  /// null 表示不修改路径。
+  /// 如需加密，拦截器会用此值替换 `RequestOptions.path`。
+  final String? path;
+
+  /// 加密后的请求体
+  ///
+  /// null 表示不修改 body。
+  /// 类型不限于 Map — 加密后通常是 base64 字符串或 bytes。
+  final Object? body;
+
+  /// 需要添加或覆盖的 headers
+  ///
+  /// null 表示不修改 headers。
+  /// 拦截器会将这些 header 合并到请求中（覆盖同名 header）。
+  final Map? headers;
+
+  /// 覆盖 Content-Type
+  ///
+  /// null 表示不修改。加密后通常是 `text/plain`（body 已是字符串，非 JSON）。
+  final String? contentType;
+
+  const EncryptedRequest({
+    this.path,
+    this.body,
+    this.headers,
+    this.contentType,
+  });
+}
diff --git a/packages/networks_sdk/lib/src/domain/repositories/networks_messaging_repository.dart b/packages/networks_sdk/lib/src/domain/repositories/networks_messaging_repository.dart
index b92ff95..6102725 100644
--- a/packages/networks_sdk/lib/src/domain/repositories/networks_messaging_repository.dart
+++ b/packages/networks_sdk/lib/src/domain/repositories/networks_messaging_repository.dart
@@ -1,49 +1,45 @@
+import 'dart:typed_data';
+
 import 'package:networks_sdk/src/domain/entities/socket_connection_state.dart';
 import 'package:networks_sdk/src/domain/entities/socket_error.dart';
 import 'package:networks_sdk/src/presentation/wiring/socket_config.dart';
 
-/// Messaging Repository Interface (Domain)
+/// Messaging Repository 接口
 abstract class NetworksMessagingRepository {
-  /// Initialize with config
   void initialize(SocketConfig config);
 
-  /// Connect to messaging server
   Future connect(String url, {String? token});
 
-  /// Disconnect from server
   Future disconnect();
 
-  /// Check if connected
   bool get isConnected;
 
-  /// Current connection state
   SocketConnectionState get connectionState;
 
-  /// Send a JSON message
+  /// Token 热更新（不断连）
+  void updateToken(String token);
+
   Future send(Map message);
 
-  /// Send a raw string message
   Future sendString(String message);
 
-  /// Stream of incoming parsed JSON messages
+  /// 发送二进制数据
+  Future sendBytes(List bytes);
+
   Stream> get messageStream;
 
-  /// Stream of raw string messages
   Stream get rawMessageStream;
 
-  /// Stream of connection state changes
+  /// 二进制消息流
+  Stream get binaryMessageStream;
+
   Stream get connectionStateStream;
 
-  /// Stream of errors
   Stream get errorStream;
 
-  /// Called when app enters foreground
   void onEnterForeground();
 
-  /// Called when app enters background
   void onEnterBackground();
 
-  /// Dispose all resources
   Future dispose();
 }
-
diff --git a/packages/networks_sdk/lib/src/domain/repositories/networks_sdk_repository.dart b/packages/networks_sdk/lib/src/domain/repositories/networks_sdk_repository.dart
index 4826893..0aa3e6c 100644
--- a/packages/networks_sdk/lib/src/domain/repositories/networks_sdk_repository.dart
+++ b/packages/networks_sdk/lib/src/domain/repositories/networks_sdk_repository.dart
@@ -1,12 +1,32 @@
 // Repository Interface（Domain）
 
+import 'package:dio/dio.dart';
 import 'package:networks_sdk/src/data/dto/api_requestable.dart';
 import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
+import 'package:networks_sdk/src/presentation/wiring/network_callbacks.dart';
 
+/// 网络层 Repository 接口
+///
+/// 定义两种请求入口：
+/// - [executeRequest] — 统一请求入口（标准 / Upload / 流式）
+/// - [executeDownload] — 带进度的文件下载（支持断点续传）
 abstract class NetworksSdkRepository {
   Future platformVersion();
 
   void initialize(ApiConfig apiConfig);
 
-  Future executeRequest(ApiRequestable request);
-}
\ No newline at end of file
+  Future executeRequest(
+    ApiRequestable request, {
+    CancelToken? cancelToken,
+  });
+
+  /// 文件下载（支持进度回调和断点续传）
+  Future executeDownload({
+    required String url,
+    required String savePath,
+    OnDownloadProgress? onProgress,
+    CancelToken? cancelToken,
+    bool resume = false,
+    Map? headers,
+  });
+}
diff --git a/packages/networks_sdk/lib/src/presentation/facade/networks_messaging_api.dart b/packages/networks_sdk/lib/src/presentation/facade/networks_messaging_api.dart
index 73348d5..d816d0c 100644
--- a/packages/networks_sdk/lib/src/presentation/facade/networks_messaging_api.dart
+++ b/packages/networks_sdk/lib/src/presentation/facade/networks_messaging_api.dart
@@ -1,92 +1,75 @@
+import 'dart:typed_data';
+
 import 'package:networks_sdk/src/domain/entities/socket_connection_state.dart';
 import 'package:networks_sdk/src/domain/entities/socket_error.dart';
 import 'package:networks_sdk/src/presentation/wiring/networks_sdk_wiring.dart';
 import 'package:networks_sdk/src/presentation/wiring/socket_config.dart';
 
-/// Messaging API for real-time communication
+/// 实时通信公开接口
 ///
-/// This abstract class provides a technology-agnostic interface for
-/// real-time messaging. The actual implementation may use WebSocket
-/// or other transport mechanisms.
+/// 底层基于 WebSocket，支持 JSON / 字符串 / 二进制消息、
+/// 自动重连（含无限重连）、Token 热更新、消息加密/解密钩子。
 ///
-/// ## Usage
+/// ## 使用方式
 ///
 /// ```dart
 /// final messaging = NetworksMessagingApi();
 /// await messaging.initialize(SocketConfig(...));
 ///
-/// // Connect to messaging server
 /// await messaging.connect('wss://api.example.com/ws', token: 'xxx');
 ///
-/// // Listen for messages
 /// messaging.messageStream.listen((msg) => print(msg));
 ///
-/// // Send messages
 /// await messaging.send({'type': 'chat', 'data': {...}});
 ///
-/// // Handle connection state
-/// messaging.connectionStateStream.listen((state) => ...);
+/// // Token 热更新（不断连）
+/// messaging.updateToken('new_token');
 ///
-/// // Handle errors
-/// messaging.errorStream.listen((error) => ...);
+/// // 发送二进制
+/// await messaging.sendBytes(Uint8List.fromList([0x01, 0x02]));
 ///
-/// // Lifecycle management
-/// messaging.onEnterForeground();
-/// messaging.onEnterBackground();
-///
-/// // Cleanup
 /// await messaging.disconnect();
 /// await messaging.dispose();
 /// ```
-abstract class NetworksMessagingApi
-{
+abstract class NetworksMessagingApi {
   factory NetworksMessagingApi() => NetworksSdkWiring.buildMessagingApi();
 
-  /// Initialize the messaging service with configuration
   void initialize(SocketConfig config);
 
-  /// Connect to the messaging server
-  ///
-  /// [url] - WebSocket URL (e.g., 'wss://api.example.com/ws')
-  /// [token] - Optional authentication token
   Future connect(String url, {String? token});
 
-  /// Disconnect from the messaging server
-  ///
-  /// Manual disconnect does not trigger auto-reconnect
   Future disconnect();
 
-  /// Check if currently connected
   bool get isConnected;
 
-  /// Current connection state
   SocketConnectionState get connectionState;
 
-  /// Send a JSON message
+  /// Token 热更新（不断开连接）
+  ///
+  /// 仅更新内部 token，下次重连自动使用新 token。
+  void updateToken(String token);
+
   Future send(Map message);
 
-  /// Send a raw string message
   Future sendString(String message);
 
-  /// Stream of incoming parsed JSON messages
+  /// 发送二进制数据
+  Future sendBytes(List bytes);
+
   Stream> get messageStream;
 
-  /// Stream of raw string messages (including failed JSON parses)
   Stream get rawMessageStream;
 
-  /// Stream of connection state changes
+  /// 二进制消息流
+  Stream get binaryMessageStream;
+
   Stream get connectionStateStream;
 
-  /// Stream of errors
   Stream get errorStream;
 
-  /// Called when app enters foreground
   void onEnterForeground();
 
-  /// Called when app enters background
   void onEnterBackground();
 
-  /// Dispose all resources
   Future dispose();
 }
-
diff --git a/packages/networks_sdk/lib/src/presentation/facade/networks_sdk_api.dart b/packages/networks_sdk/lib/src/presentation/facade/networks_sdk_api.dart
index 1a949ff..72c497d 100644
--- a/packages/networks_sdk/lib/src/presentation/facade/networks_sdk_api.dart
+++ b/packages/networks_sdk/lib/src/presentation/facade/networks_sdk_api.dart
@@ -1,19 +1,69 @@
-
-
-
+import 'package:dio/dio.dart';
 import 'package:networks_sdk/src/data/dto/api_requestable.dart';
 import 'package:networks_sdk/src/presentation/wiring/api_config.dart';
+import 'package:networks_sdk/src/presentation/wiring/network_callbacks.dart';
 import 'package:networks_sdk/src/presentation/wiring/networks_sdk_wiring.dart';
 
-
-/// SDK API
-abstract class NetworksSdkApi
-{
+/// Networks SDK 公开接口
+///
+/// 提供两种请求入口：
+/// - [executeRequest] — 统一请求入口（标准 / Upload / 流式）
+/// - [executeDownload] — 带进度的文件下载（支持断点续传）
+///
+/// 流式请求（SSE）也走 [executeRequest]，由业务 Request 类 override
+/// `decodeResponse` 处理 SSE 解析。SDK 根据 `requestType == stream`
+/// 自动切换响应类型。
+///
+/// 使用方式：
+/// ```dart
+/// final sdk = NetworksSdkApi();
+/// sdk.initialize(apiConfig);
+///
+/// // 标准请求
+/// final data = await sdk.executeRequest(LoginRequest(...));
+///
+/// // 流式请求（SSE）— 同一入口，Request 类 override decodeResponse
+/// final result = await sdk.executeRequest(VoiceTranscribeRequest(...));
+///
+/// // 文件下载
+/// await sdk.executeDownload(
+///   url: '/files/report.pdf',
+///   savePath: '/tmp/report.pdf',
+///   onProgress: (received, total) => print('$received / $total'),
+/// );
+/// ```
+abstract class NetworksSdkApi {
   factory NetworksSdkApi() => NetworksSdkWiring.build();
 
   Future platformVersion();
 
-  void initialize(ApiConfig aApiConfig);
+  void initialize(ApiConfig apiConfig);
 
-  Future executeRequest(ApiRequestable request);
+  /// 执行 API 请求 — 统一入口
+  ///
+  /// 支持标准请求、登录、上传、流式（SSE），由 `request.requestType` 控制。
+  /// 流式请求由业务 Request 类 override `decodeResponse` 处理 SSE 解析。
+  ///
+  /// [cancelToken] — 可选，用于取消正在进行的请求
+  Future executeRequest(
+    ApiRequestable request, {
+    CancelToken? cancelToken,
+  });
+
+  /// 下载文件到本地路径
+  ///
+  /// [url] — 下载 URL（完整路径或相对路径）
+  /// [savePath] — 本地保存路径
+  /// [onProgress] — 下载进度回调
+  /// [cancelToken] — 取消令牌
+  /// [resume] — 是否断点续传
+  /// [headers] — 额外请求头
+  Future executeDownload({
+    required String url,
+    required String savePath,
+    OnDownloadProgress? onProgress,
+    CancelToken? cancelToken,
+    bool resume = false,
+    Map? headers,
+  });
 }
diff --git a/packages/networks_sdk/lib/src/presentation/wiring/api_config.dart b/packages/networks_sdk/lib/src/presentation/wiring/api_config.dart
index ca73b27..f25a939 100644
--- a/packages/networks_sdk/lib/src/presentation/wiring/api_config.dart
+++ b/packages/networks_sdk/lib/src/presentation/wiring/api_config.dart
@@ -1,4 +1,3 @@
-
 import 'network_callbacks.dart';
 
 /// API 配置
@@ -13,12 +12,22 @@ class ApiConfig {
   /// 平台相关 headers（App 层注入：version、platform、channel 等）
   Map platformHeaders;
 
+  // ── 认证回调 ──
+
   /// Token 过期时的刷新回调
   final OnTokenRefresh? onTokenRefresh;
 
   /// 需要强制登出时的回调
   final OnForceLogout? onForceLogout;
 
+  /// Token 更新后的通知回调
+  ///
+  /// 在 [updateToken] 被调用且新 token 非空时触发。
+  /// App 层用于同步 token 到 WebSocket 等其他模块。
+  final void Function(String newToken)? onTokenUpdated;
+
+  // ── 基础回调 ──
+
   /// 日志输出回调（不设置则不输出日志）
   final OnLog? onLog;
 
@@ -29,12 +38,39 @@ class ApiConfig {
   /// 返回 false 则直接抛 [ApiError.noNetworkConnection]，不走网络。
   final OnCheckNetworkAvailable? onCheckNetworkAvailable;
 
+  // ── 加密回调（预留给 cipher_guard_sdk）──
+
+  /// 请求体加密回调，null 时不加密
+  final OnEncryptRequest? onEncryptRequest;
+
+  /// 响应体解密回调，null 时不解密
+  final OnDecryptResponse? onDecryptResponse;
+
+  // ── 业务错误回调 ──
+
+  /// 业务错误拦截回调
+  ///
+  /// 在 token 过期 / 强制登出判断之后执行。
+  /// 返回 true = App 层已处理，SDK 正常传递响应；
+  /// 返回 false = 未处理，SDK 继续正常流程。
+  final OnBusinessError? onBusinessError;
+
+  /// 响应变换回调
+  ///
+  /// 在 `executeRequest` 解码前调用，App 层可以统一解包
+  /// `{ code, data, message }` 结构。返回 null 表示不变换。
+  final OnTransformResponse? onTransformResponse;
+
+  // ── 错误码集合 ──
+
   /// App 层定义的 Token 过期错误码集合
   final Set tokenExpiredCodes;
 
   /// App 层定义的强制登出错误码集合
   final Set forceLogoutCodes;
 
+  // ── 重试配置 ──
+
   /// 瞬态错误最大重试次数（5xx / 超时 / 连接失败）
   ///
   /// 0 = 不重试（默认），设为 3 启用重试。
@@ -46,18 +82,50 @@ class ApiConfig {
   /// 实际延迟 = min(baseDelay * 2^attempt, 30s) + jitter
   final Duration retryBaseDelay;
 
+  // ── Token 刷新配置 ──
+
+  /// Token 刷新超时时间，防止 onTokenRefresh 卡住导致请求永远阻塞
+  final Duration tokenRefreshTimeout;
+
+  /// Token 刷新时间窗口：刷新成功后此时间内再次收到过期码直接返回成功，
+  /// 避免服务端同步延迟导致的误判
+  final Duration tokenReuseWindow;
+
+  // ── 主动刷新配置 ──
+
+  /// Token 过期时间解析回调
+  ///
+  /// App 层解析 JWT `exp` claim，用于主动刷新判断。
+  /// 未注入时不启用主动刷新。
+  final OnGetTokenExpiry? onGetTokenExpiry;
+
+  /// 主动刷新阈值：距过期不足此时间时提前刷新
+  ///
+  /// 默认 1 小时。WebSocket 重连前、App 回前台时
+  /// 自动检查并刷新即将过期的 token，避免带过期 token 发起请求。
+  final Duration proactiveRefreshThreshold;
+
   ApiConfig({
     required this.baseURL,
     this.token,
     this.platformHeaders = const {},
     this.onTokenRefresh,
     this.onForceLogout,
+    this.onTokenUpdated,
     this.onLog,
     this.onCheckNetworkAvailable,
+    this.onEncryptRequest,
+    this.onDecryptResponse,
+    this.onBusinessError,
+    this.onTransformResponse,
     this.tokenExpiredCodes = const {},
     this.forceLogoutCodes = const {},
     this.maxRetries = 0,
     this.retryBaseDelay = const Duration(seconds: 1),
+    this.tokenRefreshTimeout = const Duration(seconds: 10),
+    this.tokenReuseWindow = const Duration(seconds: 3),
+    this.onGetTokenExpiry,
+    this.proactiveRefreshThreshold = const Duration(hours: 1),
   });
 
   /// 构建默认 headers
@@ -70,6 +138,8 @@ class ApiConfig {
     final headers = {
       'Content-Type': 'application/json; charset=utf-8',
       'Accept': 'application/json',
+      'Keep-Alive': 'timeout=60',
+      // Unix 时间戳（秒），整数值，非格式化日期字符串
       'Timestamp': '${DateTime.now().millisecondsSinceEpoch ~/ 1000}',
       'APP-Request-ID': _generateRequestId(),
     };
@@ -91,8 +161,13 @@ class ApiConfig {
   }
 
   /// 更新 token
+  ///
+  /// 同时触发 [onTokenUpdated] 通知其他模块（如 WebSocket）同步 token。
   void updateToken(String? newToken) {
     token = newToken;
+    if (newToken != null && newToken.isNotEmpty) {
+      onTokenUpdated?.call(newToken);
+    }
   }
 
   /// 更新 base URL
@@ -105,4 +180,4 @@ class ApiConfig {
     final now = DateTime.now().microsecondsSinceEpoch;
     return '$now${Object().hashCode}';
   }
-}
\ No newline at end of file
+}
diff --git a/packages/networks_sdk/lib/src/presentation/wiring/network_callbacks.dart b/packages/networks_sdk/lib/src/presentation/wiring/network_callbacks.dart
index bca1b2f..7aceadf 100644
--- a/packages/networks_sdk/lib/src/presentation/wiring/network_callbacks.dart
+++ b/packages/networks_sdk/lib/src/presentation/wiring/network_callbacks.dart
@@ -1,13 +1,105 @@
 /// 网络层回调类型定义，由 App 层注入 SDK，避免 SDK 直接依赖外部实现。
 library;
 
+import 'package:networks_sdk/src/domain/entities/encrypted_request.dart';
+
+// ── 认证 ──
+
+/// Token 刷新回调，返回新 token；返回 null 表示刷新失败
 typedef OnTokenRefresh = Future Function();
 
-/// 強制登出回調
+/// 强制登出回调
 typedef OnForceLogout = void Function();
 
-/// 日誌輸出回調
+// ── Token 生命周期 ──
+
+/// 获取 token 过期时间
+///
+/// App 层解析 JWT 的 `exp` claim 返回过期时间。
+/// 返回 null 表示无法解析（非 JWT 或格式错误）。
+typedef OnGetTokenExpiry = DateTime? Function(String token);
+
+// ── 基础 ──
+
+/// 日志输出回调
 typedef OnLog = void Function(String message, {String? tag});
 
-/// 網路可用性查詢（App 層注入，SDK 在請求前調用）
-typedef OnCheckNetworkAvailable = Future Function();
\ No newline at end of file
+/// 网络可用性查询（App 层注入，SDK 在请求前调用）
+typedef OnCheckNetworkAvailable = Future Function();
+
+// ── 加密（预留给 cipher_guard_sdk）──
+
+/// HTTP 请求加密回调
+///
+/// 接收原始路径、headers、请求体，返回 [EncryptedRequest]。
+/// 拦截器根据返回值中的非 null 字段覆盖原始请求。
+///
+/// 参数说明：
+/// - [path] — 原始请求路径（如 `/api/v1/auth/login`）
+/// - [headers] — 当前请求的全部 headers（含 token、platform headers 等）
+/// - [body] — 原始请求体（可能是 Map、String、null 等）
+///
+/// App 层实现示例（X25519 + AES-256-CBC 模式）：
+/// - 加密 path → hex 编码 → 替换路径
+/// - 加密 body → base64 编码 → 替换请求体
+/// - 加密 token → 放入 X-Token header
+/// - Ed25519 签名 → 放入 X-Signature header
+/// - Content-Type → text/plain
+typedef OnEncryptRequest =
+    Future Function(
+      String path,
+      Map headers,
+      Object? body,
+    );
+
+/// HTTP 响应解密回调
+///
+/// 输入是原始响应数据（加密后可能是 String、`List`、或 Map），
+/// 返回解密后的 Map 供业务层使用。
+///
+/// [responseData] 的实际类型取决于服务端响应格式：
+/// - 加密模式下通常是 base64 字符串
+/// - 非加密模式下是 `Map`
+typedef OnDecryptResponse =
+    Future> Function(Object responseData);
+
+// ── 业务错误 ──
+
+/// 业务错误拦截回调
+///
+/// App 层统一处理特定错误码，返回 true = 已处理（SDK 不再抛错），
+/// 返回 false = 未处理（SDK 继续正常流程）。
+typedef OnBusinessError = bool Function(int code, String message, String path);
+
+/// 响应变换回调
+///
+/// App 层自定义响应解包逻辑（如统一解包 `{ code, data, message }` 结构）。
+/// 返回 null 表示不变换，使用原始响应。
+typedef OnTransformResponse =
+    Map? Function(Map raw);
+
+// ── 下载 ──
+
+/// 下载进度回调
+typedef OnDownloadProgress = void Function(int received, int total);
+
+// ── WebSocket 加密（预留给 cipher_guard_sdk）──
+
+/// WebSocket 连接 URL 构建回调
+///
+/// 建立连接前调用，接收原始 URL 和 token，返回最终的连接 URL 字符串。
+/// WS 握手本质是 HTTP GET 升级请求，只需控制 URL（路径 + 查询参数）。
+///
+/// App 层可在此（通过调用 cipher_guard_sdk）：
+/// - 加密 URL 路径（如 `/ws` → `/hex(encrypt(ws))`）
+/// - 加密 token 参数（明文 token 不出现在 URL 中）
+/// - 添加加密模式协商参数（如 `cipher=true&type=mode3`）
+///
+/// null 时使用默认行为：在 URL 后追加 `?token=xxx`。
+typedef OnBuildConnectUrl = String Function(String url, String? token);
+
+/// WebSocket 发送前加密回调
+typedef OnEncryptMessage = Future Function(String plainText);
+
+/// WebSocket 收到后解密回调
+typedef OnDecryptMessage = Future Function(String cipherText);
diff --git a/packages/networks_sdk/lib/src/presentation/wiring/networks_messaging_api_impl.dart b/packages/networks_sdk/lib/src/presentation/wiring/networks_messaging_api_impl.dart
index 2e70c56..c3906c4 100644
--- a/packages/networks_sdk/lib/src/presentation/wiring/networks_messaging_api_impl.dart
+++ b/packages/networks_sdk/lib/src/presentation/wiring/networks_messaging_api_impl.dart
@@ -1,3 +1,5 @@
+import 'dart:typed_data';
+
 import 'package:networks_sdk/src/data/repositories/networks_messaging_repository_impl.dart';
 import 'package:networks_sdk/src/domain/entities/socket_connection_state.dart';
 import 'package:networks_sdk/src/domain/entities/socket_error.dart';
@@ -5,7 +7,7 @@ import 'package:networks_sdk/src/domain/repositories/networks_messaging_reposito
 import 'package:networks_sdk/src/presentation/facade/networks_messaging_api.dart';
 import 'package:networks_sdk/src/presentation/wiring/socket_config.dart';
 
-/// Implementation of [NetworksMessagingApi] using [NetworksMessagingRepository]
+/// [NetworksMessagingApi] 的实现，透传给 [NetworksMessagingRepository]
 class NetworksMessagingApiImpl implements NetworksMessagingApi {
   NetworksMessagingRepository? _repository;
 
@@ -47,6 +49,12 @@ class NetworksMessagingApiImpl implements NetworksMessagingApi {
     return _repository!.connectionState;
   }
 
+  @override
+  void updateToken(String token) {
+    _checkInitialized();
+    _repository!.updateToken(token);
+  }
+
   @override
   Future send(Map message) {
     _checkInitialized();
@@ -59,6 +67,12 @@ class NetworksMessagingApiImpl implements NetworksMessagingApi {
     return _repository!.sendString(message);
   }
 
+  @override
+  Future sendBytes(List bytes) {
+    _checkInitialized();
+    return _repository!.sendBytes(bytes);
+  }
+
   @override
   Stream> get messageStream {
     _checkInitialized();
@@ -71,6 +85,12 @@ class NetworksMessagingApiImpl implements NetworksMessagingApi {
     return _repository!.rawMessageStream;
   }
 
+  @override
+  Stream get binaryMessageStream {
+    _checkInitialized();
+    return _repository!.binaryMessageStream;
+  }
+
   @override
   Stream get connectionStateStream {
     _checkInitialized();
@@ -103,4 +123,3 @@ class NetworksMessagingApiImpl implements NetworksMessagingApi {
     }
   }
 }
-
diff --git a/packages/networks_sdk/lib/src/presentation/wiring/networks_sdk_api_impl.dart b/packages/networks_sdk/lib/src/presentation/wiring/networks_sdk_api_impl.dart
index 8dd873c..612357e 100644
--- a/packages/networks_sdk/lib/src/presentation/wiring/networks_sdk_api_impl.dart
+++ b/packages/networks_sdk/lib/src/presentation/wiring/networks_sdk_api_impl.dart
@@ -1,7 +1,7 @@
 import '../../../networks_sdk.dart';
 import 'networks_sdk_core.dart';
 
-/// SDK API Implementation
+/// [NetworksSdkApi] 的实现，透传给 Repository
 class NetworksSdkApiImpl implements NetworksSdkApi {
   final NetworksSdkCore _core;
 
@@ -14,6 +14,29 @@ class NetworksSdkApiImpl implements NetworksSdkApi {
   void initialize(ApiConfig apiConfig) => _core.repo.initialize(apiConfig);
 
   @override
-  Future executeRequest(ApiRequestable request) => _core.repo.executeRequest(request);
+  Future executeRequest(
+    ApiRequestable request, {
+    CancelToken? cancelToken,
+  }) {
+    return _core.repo.executeRequest(request, cancelToken: cancelToken);
+  }
 
+  @override
+  Future executeDownload({
+    required String url,
+    required String savePath,
+    OnDownloadProgress? onProgress,
+    CancelToken? cancelToken,
+    bool resume = false,
+    Map? headers,
+  }) {
+    return _core.repo.executeDownload(
+      url: url,
+      savePath: savePath,
+      onProgress: onProgress,
+      cancelToken: cancelToken,
+      resume: resume,
+      headers: headers,
+    );
+  }
 }
diff --git a/packages/networks_sdk/lib/src/presentation/wiring/socket_config.dart b/packages/networks_sdk/lib/src/presentation/wiring/socket_config.dart
index 730b2ea..55f379a 100644
--- a/packages/networks_sdk/lib/src/presentation/wiring/socket_config.dart
+++ b/packages/networks_sdk/lib/src/presentation/wiring/socket_config.dart
@@ -1,9 +1,13 @@
+import 'package:networks_sdk/src/presentation/wiring/network_callbacks.dart';
+
 /// WebSocket 配置
 /// 非单例，由 App 层构造并注入到 SocketClient
 ///
 /// 与 [ApiConfig] 设计一致：SDK 不依赖 Flutter，
 /// 网络检测、生命周期等业务逻辑通过回调注入。
 class SocketConfig {
+  // ── 心跳 ──
+
   /// 应用层心跳间隔（定时发送 "ping" 字符串）
   final Duration heartbeatInterval;
 
@@ -13,10 +17,19 @@ class SocketConfig {
   /// Pong 超时（超过此时间未收到 pong 则判定连接断开）
   final Duration pongTimeout;
 
+  // ── 连接 ──
+
   /// 连接超时
   final Duration connectTimeout;
 
+  /// 是否启用 WebSocket 压缩（permessage-deflate）
+  final bool enableCompression;
+
+  // ── 重连 ──
+
   /// 最大重连次数（0 = 不重连）
+  ///
+  /// 当 [unlimitedReconnect] 为 true 时此字段无效。
   final int maxReconnectAttempts;
 
   /// 最大重连延迟（指数退避上限）
@@ -25,22 +38,65 @@ class SocketConfig {
   /// 是否自动重连
   final bool autoReconnect;
 
+  /// 无限重连模式
+  ///
+  /// IM 场景建议开启：连接断开后始终尝试重连，不受
+  /// [maxReconnectAttempts] 限制。退避延迟仍受
+  /// [maxReconnectDelay] 约束。
+  final bool unlimitedReconnect;
+
+  // ── 回调 ──
+
   /// 日志输出回调（与 ApiConfig.onLog 同签名）
-  final void Function(String message, {String? tag})? onLog;
+  final OnLog? onLog;
 
   /// 网络可用性查询（App 层注入，SDK 在重连前调用）
   /// 返回 true 表示网络可用，可以尝试重连
-  final Future Function()? onCheckNetworkAvailable;
+  final OnCheckNetworkAvailable? onCheckNetworkAvailable;
+
+  /// 重连前回调
+  ///
+  /// 每次自动重连前调用（心跳超时、连接断开等触发的内部重连）。
+  /// App 层用于：
+  /// - 检查并刷新即将过期的 token（通过 [SocketClient.updateToken]）
+  /// - 其他重连前准备工作
+  ///
+  /// 回调完成后才发起实际连接。如果回调抛出异常，本次重连跳过，
+  /// 等下一轮退避定时器触发。
+  final Future Function()? onBeforeReconnect;
+
+  // ── 加密回调（预留给 cipher_guard_sdk）──
+
+  /// 连接 URL 构建回调
+  ///
+  /// 建立连接前调用，接收原始 URL 和 token，返回最终连接 URL 字符串。
+  /// null 时使用默认行为（URL 后追加 `?token=xxx`）。
+  ///
+  /// App 层注入 cipher_guard_sdk 的加密逻辑：路径/token 加密、
+  /// 添加 `cipher=true` 参数等。
+  final OnBuildConnectUrl? onBuildConnectUrl;
+
+  /// 发送前加密回调，null 时不加密
+  final OnEncryptMessage? onEncryptMessage;
+
+  /// 收到后解密回调，null 时不解密
+  final OnDecryptMessage? onDecryptMessage;
 
   SocketConfig({
     this.heartbeatInterval = const Duration(seconds: 10),
     this.pingInterval = const Duration(seconds: 5),
     this.pongTimeout = const Duration(seconds: 10),
     this.connectTimeout = const Duration(seconds: 15),
+    this.enableCompression = false,
     this.maxReconnectAttempts = 5,
     this.maxReconnectDelay = const Duration(seconds: 30),
     this.autoReconnect = true,
+    this.unlimitedReconnect = false,
     this.onLog,
     this.onCheckNetworkAvailable,
+    this.onBeforeReconnect,
+    this.onBuildConnectUrl,
+    this.onEncryptMessage,
+    this.onDecryptMessage,
   });
 }
diff --git a/packages/notification_sdk/android/build.gradle b/packages/notification_sdk/android/build.gradle
deleted file mode 100644
index 1b803ac..0000000
--- a/packages/notification_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.notification_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.notification_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/notification_sdk/android/build.gradle.kts b/packages/notification_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..a85707c
--- /dev/null
+++ b/packages/notification_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.notification_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.notification_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/notification_sdk/ios/Classes/NotificationSdkPlugin.swift b/packages/notification_sdk/ios/Classes/NotificationSdkPlugin.swift
index a642413..af8de48 100644
--- a/packages/notification_sdk/ios/Classes/NotificationSdkPlugin.swift
+++ b/packages/notification_sdk/ios/Classes/NotificationSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class NotificationSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/notification_sdk/ios/notification_sdk.podspec b/packages/notification_sdk/ios/notification_sdk.podspec
index 9aab754..c171975 100644
--- a/packages/notification_sdk/ios/notification_sdk.podspec
+++ b/packages/notification_sdk/ios/notification_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/protocol_sdk/android/build.gradle b/packages/protocol_sdk/android/build.gradle
deleted file mode 100644
index cceae73..0000000
--- a/packages/protocol_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.protocol_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.protocol_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/protocol_sdk/android/build.gradle.kts b/packages/protocol_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..ffc8989
--- /dev/null
+++ b/packages/protocol_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.protocol_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.protocol_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/protocol_sdk/ios/Classes/ProtocolSdkPlugin.swift b/packages/protocol_sdk/ios/Classes/ProtocolSdkPlugin.swift
index 93a4115..d40120b 100644
--- a/packages/protocol_sdk/ios/Classes/ProtocolSdkPlugin.swift
+++ b/packages/protocol_sdk/ios/Classes/ProtocolSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class ProtocolSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/protocol_sdk/ios/protocol_sdk.podspec b/packages/protocol_sdk/ios/protocol_sdk.podspec
index b981a71..2cde62b 100644
--- a/packages/protocol_sdk/ios/protocol_sdk.podspec
+++ b/packages/protocol_sdk/ios/protocol_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/rtc_sdk/android/build.gradle b/packages/rtc_sdk/android/build.gradle
deleted file mode 100644
index 4fda6fc..0000000
--- a/packages/rtc_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.rtc_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.rtc_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/rtc_sdk/android/build.gradle.kts b/packages/rtc_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..19b7f66
--- /dev/null
+++ b/packages/rtc_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.rtc_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.rtc_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/rtc_sdk/ios/Classes/RtcSdkPlugin.swift b/packages/rtc_sdk/ios/Classes/RtcSdkPlugin.swift
index b24a613..c395710 100644
--- a/packages/rtc_sdk/ios/Classes/RtcSdkPlugin.swift
+++ b/packages/rtc_sdk/ios/Classes/RtcSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class RtcSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/rtc_sdk/ios/rtc_sdk.podspec b/packages/rtc_sdk/ios/rtc_sdk.podspec
index 83f62f5..ea764cf 100644
--- a/packages/rtc_sdk/ios/rtc_sdk.podspec
+++ b/packages/rtc_sdk/ios/rtc_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/packages/storage_sdk/android/build.gradle b/packages/storage_sdk/android/build.gradle
deleted file mode 100644
index 908ea2c..0000000
--- a/packages/storage_sdk/android/build.gradle
+++ /dev/null
@@ -1,66 +0,0 @@
-group = "com.example.storage_sdk"
-version = "1.0-SNAPSHOT"
-
-buildscript {
-    ext.kotlin_version = "2.2.20"
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath("com.android.tools.build:gradle:8.11.1")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
-    }
-}
-
-allprojects {
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
-
-android {
-    namespace = "com.example.storage_sdk"
-
-    compileSdk = 36
-
-    compileOptions {
-        sourceCompatibility = JavaVersion.VERSION_17
-        targetCompatibility = JavaVersion.VERSION_17
-    }
-
-    kotlinOptions {
-        jvmTarget = JavaVersion.VERSION_17
-    }
-
-    sourceSets {
-        main.java.srcDirs += "src/main/kotlin"
-        test.java.srcDirs += "src/test/kotlin"
-    }
-
-    defaultConfig {
-        minSdk = 24
-    }
-
-    dependencies {
-        testImplementation("org.jetbrains.kotlin:kotlin-test")
-        testImplementation("org.mockito:mockito-core:5.0.0")
-    }
-
-    testOptions {
-        unitTests.all {
-            useJUnitPlatform()
-
-            testLogging {
-               events "passed", "skipped", "failed", "standardOut", "standardError"
-               outputs.upToDateWhen {false}
-               showStandardStreams = true
-            }
-        }
-    }
-}
diff --git a/packages/storage_sdk/android/build.gradle.kts b/packages/storage_sdk/android/build.gradle.kts
new file mode 100644
index 0000000..1b1fdfe
--- /dev/null
+++ b/packages/storage_sdk/android/build.gradle.kts
@@ -0,0 +1,71 @@
+group = "com.example.storage_sdk"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "com.example.storage_sdk"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // Compose BOM 统一管理子库版本，按需在各 SDK 中引入具体组件
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
diff --git a/packages/storage_sdk/ios/Classes/StorageSdkPlugin.swift b/packages/storage_sdk/ios/Classes/StorageSdkPlugin.swift
index 1a9fcf9..aff3fee 100644
--- a/packages/storage_sdk/ios/Classes/StorageSdkPlugin.swift
+++ b/packages/storage_sdk/ios/Classes/StorageSdkPlugin.swift
@@ -1,4 +1,4 @@
-import Flutter
+@preconcurrency import Flutter
 import UIKit
 
 public class StorageSdkPlugin: NSObject, FlutterPlugin {
diff --git a/packages/storage_sdk/ios/storage_sdk.podspec b/packages/storage_sdk/ios/storage_sdk.podspec
index 95940cf..2239b5d 100644
--- a/packages/storage_sdk/ios/storage_sdk.podspec
+++ b/packages/storage_sdk/ios/storage_sdk.podspec
@@ -19,7 +19,7 @@ A new Flutter plugin project.
 
   # Flutter.framework does not contain a i386 slice.
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES', 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'i386' }
-  s.swift_version = '5.0'
+  s.swift_version = '6.2'
 
   # If your plugin requires a privacy manifest, for example if it uses any
   # required reason APIs, update the PrivacyInfo.xcprivacy file to describe your
diff --git a/pubspec.lock b/pubspec.lock
index 7b87f8a..ddf3fa5 100644
--- a/pubspec.lock
+++ b/pubspec.lock
@@ -9,6 +9,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "92.0.0"
+  adaptive_number:
+    dependency: transitive
+    description:
+      name: adaptive_number
+      sha256: "3a567544e9b5c9c803006f51140ad544aedc79604fd4f3f2c1380003f97c1d77"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.0.0"
   analyzer:
     dependency: transitive
     description:
@@ -241,6 +249,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "3.0.7"
+  dart_jsonwebtoken:
+    dependency: transitive
+    description:
+      name: dart_jsonwebtoken
+      sha256: c6ecb3bb991c459b91c5adf9e871113dcb32bbe8fe7ca2c92723f88ffc1e0b7a
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.3.2"
   dart_style:
     dependency: transitive
     description:
@@ -297,6 +313,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "0.2.8"
+  ed25519_edwards:
+    dependency: transitive
+    description:
+      name: ed25519_edwards
+      sha256: "6ce0112d131327ec6d42beede1e5dfd526069b18ad45dcf654f15074ad9276cd"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.3.1"
   encrypt:
     dependency: transitive
     description:
@@ -471,14 +495,6 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.0.5"
-  js:
-    dependency: transitive
-    description:
-      name: js
-      sha256: "53385261521cc4a0c4658fd0ad07a7d14591cf8fc33abbceae306ddb974888dc"
-      url: "https://pub.dev"
-    source: hosted
-    version: "0.7.2"
   json_annotation:
     dependency: transitive
     description:
@@ -720,13 +736,13 @@ packages:
     source: hosted
     version: "2.1.8"
   pointycastle:
-    dependency: transitive
+    dependency: "direct overridden"
     description:
       name: pointycastle
-      sha256: "4be0097fcf3fd3e8449e53730c631200ebc7b88016acecab2b0da2f0149222fe"
+      sha256: "92aa3841d083cc4b0f4709b5c74fd6409a3e6ba833ffc7dc6a8fee096366acf5"
       url: "https://pub.dev"
     source: hosted
-    version: "3.9.1"
+    version: "4.0.0"
   pool:
     dependency: transitive
     description:
diff --git a/pubspec.yaml b/pubspec.yaml
index 4d6e1b5..c5c5851 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -16,6 +16,12 @@ workspace:
   - packages/storage_sdk
   - packages/im_log_sdk
 
+dependency_overrides:
+  # encrypt 5.0.3 限制 pointycastle ^3.6.2，但 dart_jsonwebtoken 需要 ^4.0.0。
+  # pointycastle 4.0.0 无破坏性 API 变更（主要是新增算法和泛型改进），
+  # encrypt 在 4.0.0 下运行无问题，强制升级解决冲突。
+  pointycastle: ^4.0.0
+
 dev_dependencies:
   melos: ^7.0.0
 
diff --git a/scripts/new_sdk.sh b/scripts/new_sdk.sh
index 67e6d5e..c69c3ce 100755
--- a/scripts/new_sdk.sh
+++ b/scripts/new_sdk.sh
@@ -217,6 +217,117 @@ with open(path, 'w') as f:
     f.write(content)
 PY
 
+# ---- Step 3.5: 修正 podspec swift_version ----
+# flutter create 默认生成 swift_version = '5.0'，统一改为项目标准 6.2
+for podspec in \
+  "$PKG_DIR/ios/${PKG_NAME}.podspec" \
+  "$PKG_DIR/macos/${PKG_NAME}.podspec"; do
+  if [[ -f "$podspec" ]]; then
+    sed -i '' "s/s.swift_version = '5.0'/s.swift_version = '6.2'/" "$podspec"
+  fi
+done
+
+# Flutter SDK 尚未完整标注 Swift 6 并发属性，用 @preconcurrency import 将
+# FlutterMethodNotImplemented 等全局变量的并发警告降级，避免编译失败。
+# 注意：不在类上加 @MainActor，否则与 FlutterPlugin 协议的 nonisolated 要求冲突，
+# 导致 ConformanceIsolation 编译错误。
+for swift_file in \
+  "$PKG_DIR/ios/Classes/${PASCAL_NAME}SdkPlugin.swift" \
+  "$PKG_DIR/macos/Classes/${PASCAL_NAME}SdkPlugin.swift"; do
+  if [[ -f "$swift_file" ]]; then
+    sed -i '' \
+      's/^import Flutter$/@preconcurrency import Flutter/' \
+      "$swift_file"
+  fi
+done
+
+# ---- Step 3.6: 替换 Android build.gradle → build.gradle.kts（Kotlin DSL + Compose） ----
+# flutter create 默认生成 Groovy build.gradle，统一替换为 Kotlin DSL
+ANDROID_DIR="$PKG_DIR/android"
+[[ -f "$ANDROID_DIR/build.gradle" ]] && rm "$ANDROID_DIR/build.gradle"
+
+cat > "$ANDROID_DIR/build.gradle.kts" << GRADLE_EOF
+group = "com.example.${PKG_NAME}"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    val kotlinVersion = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:\$kotlinVersion")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+    // 若该 SDK 需要 Compose，取消注释下面两行，并在 dependencies 中加 compose runtime
+    // id("org.jetbrains.kotlin.plugin.compose")
+}
+
+android {
+    namespace = "com.example.${PKG_NAME}"
+    compileSdk = 36
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    sourceSets {
+        getByName("main") { java.srcDirs("src/main/kotlin") }
+        getByName("test") { java.srcDirs("src/test/kotlin") }
+    }
+
+    defaultConfig {
+        minSdk = 24
+    }
+
+    // 若该 SDK 需要 Compose，取消注释
+    // buildFeatures { compose = true }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            all {
+                it.useJUnitPlatform()
+                it.outputs.upToDateWhen { false }
+                it.testLogging {
+                    events("passed", "skipped", "failed", "standardOut", "standardError")
+                    showStandardStreams = true
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    // 若该 SDK 需要 Compose，取消注释以下两行并按需引入具体组件：
+    // val composeBom = platform("androidx.compose:compose-bom:2025.05.01")
+    // implementation(composeBom)
+    // implementation("androidx.compose.runtime:runtime")
+    testImplementation("org.jetbrains.kotlin:kotlin-test")
+    testImplementation("org.mockito:mockito-core:5.0.0")
+}
+GRADLE_EOF
+
 # ---- Step 4: IDE 配置 ----
 echo "[4/5] Updating IDE config..."
 

From 9610c455ec26348c487603ad2c8a778570965eb7 Mon Sep 17 00:00:00 2001
From: Cody 
Date: Sun, 8 Mar 2026 21:13:48 +0800
Subject: [PATCH 2/5] =?UTF-8?q?=E4=BC=98=E5=8C=96=20demo?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Doc/IM_App_架构设计.html                      |  8 +++-
 .../lib/features/chat/presentation/.gitkeep   |  0
 .../chat/presentation/chat_db_test_state.dart | 39 +++++++++++++++++++
 .../presentation/chat_db_test_view_model.dart | 38 ++----------------
 .../features/chat/view/chat_db_test_page.dart |  2 +-
 .../features/settings/view/theme_view.dart    | 13 ++-----
 .../view/widgets/theme_option_tile.dart       | 12 ++----
 7 files changed, 59 insertions(+), 53 deletions(-)
 delete mode 100644 apps/im_app/lib/features/chat/presentation/.gitkeep
 create mode 100644 apps/im_app/lib/features/chat/presentation/chat_db_test_state.dart

diff --git a/Doc/IM_App_架构设计.html b/Doc/IM_App_架构设计.html
index 2793eac..8d9dde1 100644
--- a/Doc/IM_App_架构设计.html
+++ b/Doc/IM_App_架构设计.html
@@ -3205,7 +3205,13 @@ flowchart LR
 
    两大核心逻辑：
    
 
    1. MVVM 分层职责：View（view/）只负责渲染和用户交互，ViewModel（presentation/）持有状态并处理业务逻辑，Model（model/ + entities/）定义数据结构 —— 三者通过 Riverpod Provider 连接，职责严格分离。
    
 
    2. Riverpod 单向数据流：用户操作 → ref.read(vm.notifier).action() → ViewModel 处理逻辑 → state = newState → ref.watch(vm) 检测变化 → View 自动 rebuild。数据永远单向流动，UI 永远是状态的函数。
    
-
    3. Widget 纯展示原则：View（Widget）层对业务数据严格只读。所有逻辑（导航、CRUD、状态变更、条件判断）必须在 ViewModel 中完成，View 只调用 ViewModel 方法并渲染返回的 State。包括 demo/测试页面也不例外。
    
+
    3. Widget 纯展示原则：build() 只做一件事——把 State 属性映射成 Widget 树，不允许出现任何计算或逻辑。
    
+
      
+
    • 派生显示值必须是 State getter：凡是需要从 State 字段推导出另一个值（文本、颜色、样式等），一律写成 State 的 getter，Widget 只读取结果。例如：String get buttonLabel => testStarted ? '结束' : '开始';，Widget 写 state.buttonLabel，不在 build() 里写三元。
      • 
+
    • 禁止 build() 内定义局部计算变量：final isSelected = current == mode 这类从构造参数/state 派生值的局部变量，不属于 build()。组件应接受已算好的 bool isSelected 参数，由父级或 State getter 负责计算。
      • 
+
    • 导航、CRUD、状态变更全部在 ViewModel 中完成，Widget 只转发事件：onTap: () => ref.read(vm.notifier).doAction()。
      • 
+
    • demo/测试页面同样适用：demo 代码是示范，别人会照着模仿，写法必须与正式页面完全一致。
      • 
+
    
 
 
 
    
diff --git a/apps/im_app/lib/features/chat/presentation/.gitkeep b/apps/im_app/lib/features/chat/presentation/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/apps/im_app/lib/features/chat/presentation/chat_db_test_state.dart b/apps/im_app/lib/features/chat/presentation/chat_db_test_state.dart
new file mode 100644
index 0000000..c37e5ba
--- /dev/null
+++ b/apps/im_app/lib/features/chat/presentation/chat_db_test_state.dart
@@ -0,0 +1,39 @@
+// 数据库测试页状态（Demo，正式开发后随页面一并删除）
+
+/// 单条测试结果记录
+class TestResult {
+  final String title;
+  final String subtitle;
+  final String duration;
+
+  TestResult({
+    required this.title,
+    required this.subtitle,
+    required this.duration,
+  });
+}
+
+class ChatDbTestState {
+  final bool testStarted;
+  final List testResults;
+  final String currentState;
+
+  const ChatDbTestState({
+    this.testStarted = false,
+    this.testResults = const [],
+    this.currentState = '',
+  });
+
+  /// 按钮文案（Widget 直接读，不在 View 层做判断）
+  String get buttonLabel => testStarted ? '结束' : '开始';
+
+  ChatDbTestState copyWith({
+    bool? testStarted,
+    List? testResults,
+    String? currentState,
+  }) => ChatDbTestState(
+    testStarted: testStarted ?? this.testStarted,
+    testResults: testResults ?? this.testResults,
+    currentState: currentState ?? this.currentState,
+  );
+}
diff --git a/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart b/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart
index 1abaa52..4386f91 100644
--- a/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart
+++ b/apps/im_app/lib/features/chat/presentation/chat_db_test_view_model.dart
@@ -6,42 +6,12 @@ import 'package:im_app/app/di/db_provider.dart';
 import 'package:im_app/data/local/drift/app_database.dart';
 import 'package:riverpod_annotation/riverpod_annotation.dart';
 
+import 'chat_db_test_state.dart';
+
+export 'chat_db_test_state.dart';
+
 part 'chat_db_test_view_model.g.dart';
 
-class TestResult {
-  final String title;
-  final String subtitle;
-  final String duration;
-
-  TestResult({
-    required this.title,
-    required this.subtitle,
-    required this.duration,
-  });
-}
-
-class ChatDbTestState {
-  final bool testStarted;
-  final List testResults;
-  final String currentState;
-
-  const ChatDbTestState({
-    this.testStarted = false,
-    this.testResults = const [],
-    this.currentState = '',
-  });
-
-  ChatDbTestState copyWith({
-    bool? testStarted,
-    List? testResults,
-    String? currentState,
-  }) => ChatDbTestState(
-    testStarted: testStarted ?? this.testStarted,
-    testResults: testResults ?? this.testResults,
-    currentState: currentState ?? this.currentState,
-  );
-}
-
 @riverpod
 class ChatDbTestViewModel extends _$ChatDbTestViewModel {
   @override
diff --git a/apps/im_app/lib/features/chat/view/chat_db_test_page.dart b/apps/im_app/lib/features/chat/view/chat_db_test_page.dart
index 95c1f01..3c8c025 100644
--- a/apps/im_app/lib/features/chat/view/chat_db_test_page.dart
+++ b/apps/im_app/lib/features/chat/view/chat_db_test_page.dart
@@ -30,7 +30,7 @@ class ChatDbTestPage extends ConsumerWidget {
               mainAxisAlignment: MainAxisAlignment.spaceBetween,
               children: [
                 AppButton.inverse(
-                  label: state.testStarted ? '结束' : '开始',
+                  label: state.buttonLabel,
                   onPressed: () => vm.toggleDBTest(),
                 ),
                 SizedBox(width: 8),
diff --git a/apps/im_app/lib/features/settings/view/theme_view.dart b/apps/im_app/lib/features/settings/view/theme_view.dart
index e3e96a9..3151cb9 100644
--- a/apps/im_app/lib/features/settings/view/theme_view.dart
+++ b/apps/im_app/lib/features/settings/view/theme_view.dart
@@ -16,32 +16,27 @@ class ThemeView extends ConsumerWidget {
     final current = ref.watch(themeViewModelProvider);
 
     return Scaffold(
-      appBar: AppBar(
-        title: const Text('主题'),
-      ),
+      appBar: AppBar(title: const Text('主题')),
       body: ListView(
         children: [
           const SettingsSectionHeader(title: '外观'),
           ThemeOptionTile(
             label: '跟随系统',
-            mode: ThemeMode.system,
-            current: current,
+            isSelected: current == ThemeMode.system,
             onTap: () => ref
                 .read(themeViewModelProvider.notifier)
                 .setMode(ThemeMode.system),
           ),
           ThemeOptionTile(
             label: '黑色模式',
-            mode: ThemeMode.dark,
-            current: current,
+            isSelected: current == ThemeMode.dark,
             onTap: () => ref
                 .read(themeViewModelProvider.notifier)
                 .setMode(ThemeMode.dark),
           ),
           ThemeOptionTile(
             label: '白色模式',
-            mode: ThemeMode.light,
-            current: current,
+            isSelected: current == ThemeMode.light,
             onTap: () => ref
                 .read(themeViewModelProvider.notifier)
                 .setMode(ThemeMode.light),
diff --git a/apps/im_app/lib/features/settings/view/widgets/theme_option_tile.dart b/apps/im_app/lib/features/settings/view/widgets/theme_option_tile.dart
index d270d9f..92b1df5 100644
--- a/apps/im_app/lib/features/settings/view/widgets/theme_option_tile.dart
+++ b/apps/im_app/lib/features/settings/view/widgets/theme_option_tile.dart
@@ -5,14 +5,13 @@ import '../../../../../core/ui/base/context_theme_ext.dart';
 /// 单个主题选项行
 ///
 /// 纯展示 + 事件透传，不感知任何 Provider。
-/// 由父级传入 [current] 判断选中状态，[onTap] 处理切换。
+/// 父级传入 [isSelected] 决定是否显示勾选图标，[onTap] 处理切换。
 ///
 /// 用法：
 /// ```dart
 /// ThemeOptionTile(
 ///   label: '黑色模式',
-///   mode: ThemeMode.dark,
-///   current: current,
+///   isSelected: current == ThemeMode.dark,
 ///   onTap: () => ref.read(themeViewModelProvider.notifier).setMode(ThemeMode.dark),
 /// )
 /// ```
@@ -20,20 +19,17 @@ class ThemeOptionTile extends StatelessWidget {
   const ThemeOptionTile({
     super.key,
     required this.label,
-    required this.mode,
-    required this.current,
+    required this.isSelected,
     required this.onTap,
   });
 
   final String label;
-  final ThemeMode mode;
-  final ThemeMode current;
+  final bool isSelected;
   final VoidCallback onTap;
 
   @override
   Widget build(BuildContext context) {
     final s = context.styles;
-    final isSelected = current == mode;
 
     return ListTile(
       title: Text(label),

From 132349c410776a1450e6d4a81563794e34ba2dd3 Mon Sep 17 00:00:00 2001
From: Cody 
Date: Sun, 8 Mar 2026 21:38:25 +0800
Subject: [PATCH 3/5] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E5=BC=95=E8=B5=B7=E7=9A=84=20demo=20bug?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../login/presentation/login_view_model.dart       | 14 +++++++++++++-
 .../im_app/lib/features/login/view/login_page.dart | 11 ++++++-----
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/apps/im_app/lib/features/login/presentation/login_view_model.dart b/apps/im_app/lib/features/login/presentation/login_view_model.dart
index 89f1adb..7552100 100644
--- a/apps/im_app/lib/features/login/presentation/login_view_model.dart
+++ b/apps/im_app/lib/features/login/presentation/login_view_model.dart
@@ -59,6 +59,10 @@ class LoginViewModel extends _$LoginViewModel {
   /// 仅用于演示路由守卫行为，正式 UI 就绪后删除此方法，改用 [login]。
   /// 正式 [login] 成功后同样需要调用 [AuthNotifier.login] 更新守卫状态。
   Future demoLogin() async {
+    // 防止连点重入：第一次调用未完成前忽略后续调用
+    if (state.isLoading) return;
+    state = state.copyWith(isLoading: true, error: null);
+
     try {
       final storageApi = ref.read(storageSdkProvider);
       final storageLifeCycle = storageApi as StorageSdkLifecycle;
@@ -72,11 +76,15 @@ class LoginViewModel extends _$LoginViewModel {
       // 先完成 DB 操作，再标记登录状态（失败时不会误标为已登录）
       await storageLifeCycle.openDatabase(user.uid);
       final userCompanion = UserDto.fromEntity(user).toCompanion();
-      await storageApi.insert(userCompanion);
+      await storageApi.insertOrReplace(userCompanion);
 
       // 全部成功后再更新登录状态，触发路由守卫重定向
+      // 注意：login() 触发导航后 provider 随即被 dispose，之后不能再写 state
+      if (!ref.mounted) return;
       ref.read(authNotifierProvider).login();
     } catch (e) {
+      // 导航已发生时 provider 已被 dispose，静默丢弃，不再写 state
+      if (!ref.mounted) return;
       state = state.copyWith(error: e.toString(), isLoading: false);
     }
   }
@@ -94,15 +102,19 @@ class LoginViewModel extends _$LoginViewModel {
           .read(loginUseCaseProvider)
           .execute(email: email, password: password);
 
+      if (!ref.mounted) return;
       state = state.copyWith(user: user, isLoading: false);
     } on FormatException catch (e) {
       // 格式校验失败（UseCase 层抛出）
+      if (!ref.mounted) return;
       state = state.copyWith(error: e.message, isLoading: false);
     } on ApiError catch (e) {
       // 网络 / 服务端错误（Repository → SDK 透传）
+      if (!ref.mounted) return;
       state = state.copyWith(error: e.displayMessage, isLoading: false);
     } catch (e) {
       // 兜底：防止未预期的异常导致 isLoading 死锁
+      if (!ref.mounted) return;
       state = state.copyWith(error: e.toString(), isLoading: false);
     }
   }
diff --git a/apps/im_app/lib/features/login/view/login_page.dart b/apps/im_app/lib/features/login/view/login_page.dart
index dcfe9ab..c907581 100644
--- a/apps/im_app/lib/features/login/view/login_page.dart
+++ b/apps/im_app/lib/features/login/view/login_page.dart
@@ -15,13 +15,12 @@ class LoginPage extends ConsumerWidget {
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    // ref.watch 保持 loginViewModelProvider 存活（AutoDispose 需要至少一个监听者）
+    final state = ref.watch(loginViewModelProvider);
     final s = context.styles;
 
     return Scaffold(
-      appBar: AppBar(
-        title: const Text('登录'),
-        automaticallyImplyLeading: false,
-      ),
+      appBar: AppBar(title: const Text('登录'), automaticallyImplyLeading: false),
       body: Center(
         child: Column(
           mainAxisSize: MainAxisSize.min,
@@ -34,7 +33,9 @@ class LoginPage extends ConsumerWidget {
             ),
             const SizedBox(height: 32),
             FilledButton(
-              onPressed: () => ref.read(loginViewModelProvider.notifier).demoLogin(),
+              onPressed: state.isLoading
+                  ? null
+                  : () => ref.read(loginViewModelProvider.notifier).demoLogin(),
               child: const Text('登录'),
             ),
           ],

From a063ce178e03012331b3028e3186e1ad32a00880 Mon Sep 17 00:00:00 2001
From: Cody 
Date: Mon, 9 Mar 2026 09:06:39 +0800
Subject: [PATCH 4/5] =?UTF-8?q?=E5=8A=A0=E8=A7=A3=E5=AF=86=E6=80=A7?=
 =?UTF-8?q?=E8=83=BD=E4=BC=98=E5=8C=96=EF=BC=8C=E9=A2=84=E5=9F=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Doc/IM_App_架构设计.html                      |  10 +-
 apps/im_app/lib/app/di/app_providers.dart     |  11 +-
 apps/im_app/lib/app/di/network_provider.dart  |  20 +++-
 .../encryption_flutter_service.dart           | 106 +++++++++++++++---
 .../facade/cipher_guard_sdk_api.dart          |  31 +++++
 .../wiring/cipher_guard_sdk_api_impl.dart     |  43 +++++++
 6 files changed, 199 insertions(+), 22 deletions(-)

diff --git a/Doc/IM_App_架构设计.html b/Doc/IM_App_架构设计.html
index 8d9dde1..12edacb 100644
--- a/Doc/IM_App_架构设计.html
+++ b/Doc/IM_App_架构设计.html
@@ -427,6 +427,14 @@
                 • 日志与监控系统
 
                 Part 7：总结
+
+                Part 8：UI 设计规范
+                • 核心约定
+                • 颜色体系
+                • 字体体系
+                • 组件 — Button
+                • 业务弹框 — Dialog
+                • 图标规范
             
         
 
@@ -6507,7 +6515,7 @@ class UploadFileRequest extends ApiRequestable<UploadResult>
 }
 
    
 
-
    模式 B：二进制上传到 S3 presigned URL（参考 LingoDot-Flutter）
    
+
    模式 B：二进制上传到 S3 presigned URL
    
 
 
    先向后端获取 presigned URL，再直接上传到 S3：
    
 
diff --git a/apps/im_app/lib/app/di/app_providers.dart b/apps/im_app/lib/app/di/app_providers.dart
index c5e6f28..c76c412 100644
--- a/apps/im_app/lib/app/di/app_providers.dart
+++ b/apps/im_app/lib/app/di/app_providers.dart
@@ -23,11 +23,18 @@ class AuthNotifier extends ChangeNotifier {
 
   void login() {
     _isLoggedIn = true;
+    // TODO: 接入 cipher_guard_sdk 后，在此处完成 RSA 密钥注入：
+    // 1. 从安全存储（keychain / secure storage）读取公私钥对（只读一次）
+    // 2. cipherSdk.setActiveKeyPair(publicKey: pubPem, privateKey: privPem)
+    // 须在 notifyListeners() 之前完成，确保路由跳转后 onEncryptRequest 回调触发时密钥已就绪。
     notifyListeners();
   }
 
   void logout() {
     _isLoggedIn = false;
+    // TODO: 接入 cipher_guard_sdk 后，退出登录时清除内存密钥：
+    // cipherSdk.clearActiveKeyPair()
+    // cipherSdk.clearDerivedKeyCache()
     notifyListeners();
   }
 }
@@ -37,9 +44,7 @@ class AuthNotifier extends ChangeNotifier {
 /// 使用 [Provider] 持有 [AuthNotifier] 单例。
 /// go_router 通过 [GoRouter.refreshListenable] 直接监听 [AuthNotifier]（ChangeNotifier），
 /// Riverpod 侧不需要响应式更新（导航由 go_router 接管）。
-final authNotifierProvider = Provider(
-  (ref) => AuthNotifier(),
-);
+final authNotifierProvider = Provider((ref) => AuthNotifier());
 
 // ── 主题 ──────────────────────────────────────────────────────────────────────
 
diff --git a/apps/im_app/lib/app/di/network_provider.dart b/apps/im_app/lib/app/di/network_provider.dart
index d02678e..be1fd35 100644
--- a/apps/im_app/lib/app/di/network_provider.dart
+++ b/apps/im_app/lib/app/di/network_provider.dart
@@ -99,8 +99,24 @@ final apiConfigProvider = Provider((ref) {
       tokenStream.add(newToken);
     },
     onCheckNetworkAvailable: () async => networkMonitor.isConnected,
-    onEncryptRequest: null, // TODO: 接入 cipher_guard_sdk 后注入请求加密回调
-    onDecryptResponse: null, // TODO: 接入 cipher_guard_sdk 后注入响应解密回调
+    // TODO: 接入 cipher_guard_sdk 后注入请求加密回调。
+    // 前提：AuthNotifier.login() 中已完成 cipherSdk.setActiveKeyPair(pub, priv)。
+    // 示例：
+    //   onEncryptRequest: (path, headers, body) async {
+    //     final encryptedKey = await cipherSdk.encryptSessionKeyWithActiveKey(
+    //       sessionKey: currentSessionKey,
+    //     );
+    //     return EncryptedRequest(body: encryptedBody, headers: {'X-Key': encryptedKey});
+    //   },
+    onEncryptRequest: null,
+    // TODO: 接入 cipher_guard_sdk 后注入响应解密回调。
+    // 前提：与 onEncryptRequest 配套，服务端响应同样加密时启用。
+    // 示例：
+    //   onDecryptResponse: (data) async {
+    //     final plaintext = await cipherSdk.decryptMessage(encryptedData: data as String, ...);
+    //     return jsonDecode(plaintext) as Map;
+    //   },
+    onDecryptResponse: null,
     onBusinessError: null, // TODO: 接入业务错误统一处理（弹窗 / Toast / 跳转等）
     onTransformResponse:
         null, // TODO: 如后端响应格式非标准，在此归一化为 { code, data, message }
diff --git a/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart b/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart
index cd23a12..56ee26e 100644
--- a/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart
+++ b/packages/cipher_guard_sdk/lib/src/data/datasources/encryption_flutter_service.dart
@@ -21,12 +21,12 @@ import 'package:pointycastle/random/fortuna_random.dart';
 /// 密钥派生模式
 ///
 /// 决定 [EncryptionFlutterService._deriveKeyForRound] 使用哪种算法。
-/// 默认 [md5]（UU 兼容），可选 [pbkdf2]（增强安全性）。
+/// 默认 [md5]，可选 [pbkdf2]（增强安全性）。
 ///
 /// 解密旧数据时必须使用加密时相同的模式，
 /// 通过消息的 version 字段区分。
 enum KdfMode {
-  /// MD5 简单哈希（UU 兼容默认模式）
+  /// MD5 简单哈希（默认模式）
   ///
   /// 适用于 session key 已是 32 字节强随机值的场景。
   /// 性能好，每次调用 < 0.1ms。
@@ -48,14 +48,26 @@ enum KdfMode {
 ///
 /// - **RSA 密钥生成**：通过 [generateRsaKeyPairAsync] 在 Isolate 中运行，
 ///   避免阻塞主线程（1024-bit 约 150ms，2048-bit 约 300ms）
-/// - **派生密钥缓存**：[_deriveKeyForRound] 结果按 (sessionKey, round) 缓存，
-///   同一 session 的重复加解密直接命中缓存
+/// - **RSA 解析缓存**：[_parsePublicKey] / [_parsePrivateKey] 缓存 ASN1 解析结果，
+///   同一密钥 PEM 只做一次 BigInt 构造，后续命中缓存（LRU，上限 8 条）
+/// - **Session key bytes 缓存**：[_getSessionKeyBytes] 缓存 base64 → Uint8List 结果，
+///   同一 session 的多条消息只解码一次（LRU，上限 64 条）
+/// - **派生密钥缓存**：[_deriveKeyForRound] 结果按 (sessionKey, round, mode) 缓存，
+///   同一 session + round 的重复加解密直接命中（LRU，上限 64 条）
 /// - **Random.secure() 复用**：全局单例，不再每次调用创建新实例
-/// - **KDF 双模式**：MD5（默认，UU 兼容）/ PBKDF2（可选，增强安全性）
+/// - **KDF 双模式**：MD5（默认）/ PBKDF2（可选，增强安全性）
+///
+/// ## 正确的接入姿势（避免重复读文件）
+///
+/// 调用方（App 层）在登录后调一次 [CipherGuardSdkApi.setActiveKeyPair]，
+/// 把从安全存储读出的公私钥注入 SDK 内存。后续加解密使用
+/// [CipherGuardSdkApi.encryptSessionKeyWithActiveKey] /
+/// [CipherGuardSdkApi.decryptSessionKeyWithActiveKey]，
+/// 不再每次传 key 参数，也不再重复读文件。
 class EncryptionFlutterService {
   // ==================== 配置 ====================
 
-  /// 密钥派生模式，默认 MD5（UU 兼容）
+  /// 密钥派生模式，默认 MD5
   final KdfMode kdfMode;
 
   /// PBKDF2 迭代次数（仅 PBKDF2 模式有效，默认 10000）
@@ -71,6 +83,8 @@ class EncryptionFlutterService {
   static const int sessionKeySize = 32;
   static const int gcmIvLength = 12;
   static const int _maxDerivedKeyCacheSize = 64;
+  static const int _maxRsaKeyCacheSize = 8;
+  static const int _maxSessionKeyBytesCacheSize = 64;
 
   // ==================== 性能优化：复用 Random 实例 ====================
 
@@ -88,6 +102,25 @@ class EncryptionFlutterService {
   /// 清空派生密钥缓存（session key 轮换时调用）
   void clearDerivedKeyCache() => _derivedKeyCache.clear();
 
+  // ==================== 性能优化：RSA 解析缓存 ====================
+
+  /// RSA 公钥解析缓存：PEM -> RSAPublicKey
+  ///
+  /// RSA 密钥生命周期长（通常每设备一对），ASN1 解析 + BigInt 构造代价较高。
+  /// 解析结果在内存中复用，省去重复解析开销。上限 8 条，满时淘汰最早。
+  final _rsaPublicKeyCache = {};
+
+  /// RSA 私钥解析缓存：PEM -> RSAPrivateKey
+  final _rsaPrivateKeyCache = {};
+
+  // ==================== 性能优化：session key bytes 缓存 ====================
+
+  /// Session key Base64 → 字节缓存
+  ///
+  /// _deriveKeyForRound 和 _pbkdf2Derive 每次都需要 base64Decode(sessionKey)，
+  /// 对同一会话的多条消息重复解码。缓存后只解码一次，满时淘汰最早。
+  final _sessionKeyBytesCache = {};
+
   // ==================== RSA 密钥管理 ====================
 
   /// 生成 RSA 密钥对（同步，阻塞主线程）
@@ -419,7 +452,7 @@ class EncryptionFlutterService {
     switch (kdfMode) {
       case KdfMode.md5:
         // 将 sessionKey + round 一起参与 hash，保证不同 round 产出不同密钥
-        final keyBytes = base64Decode(sessionKey);
+        final keyBytes = _getSessionKeyBytes(sessionKey);
         final roundBytes = utf8.encode(':$targetRound');
         final combined = Uint8List(keyBytes.length + roundBytes.length)
           ..setRange(0, keyBytes.length, keyBytes)
@@ -449,7 +482,7 @@ class EncryptionFlutterService {
   /// 迭代次数由 [pbkdf2Iterations] 控制（默认 10000）。
   /// 输出 16 字节（AES-128 密钥）。
   Uint8List _pbkdf2Derive(String sessionKey, int targetRound) {
-    final keyBytes = base64Decode(sessionKey);
+    final keyBytes = _getSessionKeyBytes(sessionKey);
     final salt = utf8.encode('round:$targetRound');
 
     final derivator = PBKDF2KeyDerivator(HMac(SHA256Digest(), 64));
@@ -460,14 +493,20 @@ class EncryptionFlutterService {
     return derivator.process(Uint8List.fromList(keyBytes));
   }
 
-  /// 解析 RSA 公钥 PEM
+  /// 解析 RSA 公钥 PEM（带缓存）
   RSAPublicKey _parsePublicKey(String pem) {
-    final base64 = pem
+    final cached = _rsaPublicKeyCache.remove(pem);
+    if (cached != null) {
+      _rsaPublicKeyCache[pem] = cached;
+      return cached;
+    }
+
+    final b64 = pem
         .replaceAll('-----BEGIN PUBLIC KEY-----', '')
         .replaceAll('-----END PUBLIC KEY-----', '')
         .replaceAll('\n', '')
         .trim();
-    final bytes = base64Decode(base64);
+    final bytes = base64Decode(b64);
 
     final asn1Parser = ASN1Parser(Uint8List.fromList(bytes));
     final topLevelSeq = asn1Parser.nextObject() as ASN1Sequence;
@@ -480,20 +519,32 @@ class EncryptionFlutterService {
     final modulus = keySeq.elements[0] as ASN1Integer;
     final publicExponent = keySeq.elements[1] as ASN1Integer;
 
-    return RSAPublicKey(
+    final key = RSAPublicKey(
       modulus.valueAsBigInteger,
       publicExponent.valueAsBigInteger,
     );
+
+    if (_rsaPublicKeyCache.length >= _maxRsaKeyCacheSize) {
+      _rsaPublicKeyCache.remove(_rsaPublicKeyCache.keys.first);
+    }
+    _rsaPublicKeyCache[pem] = key;
+    return key;
   }
 
-  /// 解析 RSA 私钥 PEM
+  /// 解析 RSA 私钥 PEM（带缓存）
   RSAPrivateKey _parsePrivateKey(String pem) {
-    final base64 = pem
+    final cached = _rsaPrivateKeyCache.remove(pem);
+    if (cached != null) {
+      _rsaPrivateKeyCache[pem] = cached;
+      return cached;
+    }
+
+    final b64 = pem
         .replaceAll('-----BEGIN PRIVATE KEY-----', '')
         .replaceAll('-----END PRIVATE KEY-----', '')
         .replaceAll('\n', '')
         .trim();
-    final bytes = base64Decode(base64);
+    final bytes = base64Decode(b64);
 
     final asn1Parser = ASN1Parser(Uint8List.fromList(bytes));
     final keySeq = asn1Parser.nextObject() as ASN1Sequence;
@@ -503,12 +554,35 @@ class EncryptionFlutterService {
     final p = keySeq.elements[4] as ASN1Integer;
     final q = keySeq.elements[5] as ASN1Integer;
 
-    return RSAPrivateKey(
+    final key = RSAPrivateKey(
       modulus.valueAsBigInteger,
       privateExponent.valueAsBigInteger,
       p.valueAsBigInteger,
       q.valueAsBigInteger,
     );
+
+    if (_rsaPrivateKeyCache.length >= _maxRsaKeyCacheSize) {
+      _rsaPrivateKeyCache.remove(_rsaPrivateKeyCache.keys.first);
+    }
+    _rsaPrivateKeyCache[pem] = key;
+    return key;
+  }
+
+  /// session key Base64 → 字节（带缓存）
+  ///
+  /// 同一 session key 在多条消息加解密中反复 decode，缓存后只做一次。
+  Uint8List _getSessionKeyBytes(String sessionKey) {
+    final cached = _sessionKeyBytesCache.remove(sessionKey);
+    if (cached != null) {
+      _sessionKeyBytesCache[sessionKey] = cached;
+      return cached;
+    }
+    final bytes = base64Decode(sessionKey);
+    if (_sessionKeyBytesCache.length >= _maxSessionKeyBytesCacheSize) {
+      _sessionKeyBytesCache.remove(_sessionKeyBytesCache.keys.first);
+    }
+    _sessionKeyBytesCache[sessionKey] = bytes;
+    return bytes;
   }
 
   /// Hex 字符串转字节
diff --git a/packages/cipher_guard_sdk/lib/src/presentation/facade/cipher_guard_sdk_api.dart b/packages/cipher_guard_sdk/lib/src/presentation/facade/cipher_guard_sdk_api.dart
index e8a56cb..45d0f86 100644
--- a/packages/cipher_guard_sdk/lib/src/presentation/facade/cipher_guard_sdk_api.dart
+++ b/packages/cipher_guard_sdk/lib/src/presentation/facade/cipher_guard_sdk_api.dart
@@ -65,6 +65,37 @@ abstract class CipherGuardSdkApi {
     required int round,
   });
 
+  // ==================== 活跃密钥注册 ====================
+
+  /// 注册当前用户的 RSA 密钥对（登录后调用一次，内存持久化）
+  ///
+  /// 登录成功后从安全存储 / keychain 取出密钥对，调用此方法注入 SDK。
+  /// 后续 [encryptSessionKeyWithActiveKey] / [decryptSessionKeyWithActiveKey]
+  /// 直接使用内存中的密钥，不再需要调用方每次传参，也不再重复读文件。
+  ///
+  /// 退出登录时调用 [clearActiveKeyPair]。
+  void setActiveKeyPair({
+    required String publicKey,
+    required String privateKey,
+  });
+
+  /// 清除内存中的活跃密钥对（退出登录时调用）
+  void clearActiveKeyPair();
+
+  /// 用内存中的 RSA 公钥加密 session key
+  ///
+  /// 等价于 [encryptSessionKey]，但无需每次传 publicKey。
+  /// 调用前必须先调 [setActiveKeyPair]，否则抛 [StateError]。
+  Future encryptSessionKeyWithActiveKey({required String sessionKey});
+
+  /// 用内存中的 RSA 私钥解密 session key
+  ///
+  /// 等价于 [decryptSessionKey]，但无需每次传 privateKey。
+  /// 调用前必须先调 [setActiveKeyPair]，否则抛 [StateError]。
+  Future decryptSessionKeyWithActiveKey({
+    required String encryptedSessionKey,
+  });
+
   // ==================== 缓存管理 ====================
 
   /// 清空派生密钥缓存
diff --git a/packages/cipher_guard_sdk/lib/src/presentation/wiring/cipher_guard_sdk_api_impl.dart b/packages/cipher_guard_sdk/lib/src/presentation/wiring/cipher_guard_sdk_api_impl.dart
index a6b5ada..4ec700c 100644
--- a/packages/cipher_guard_sdk/lib/src/presentation/wiring/cipher_guard_sdk_api_impl.dart
+++ b/packages/cipher_guard_sdk/lib/src/presentation/wiring/cipher_guard_sdk_api_impl.dart
@@ -10,6 +10,11 @@ class CipherGuardSdkApiImpl implements CipherGuardSdkApi {
 
   CipherGuardSdkApiImpl({required CipherGuardSdkCore core}) : _core = core;
 
+  // ── 活跃密钥内存存储（登录后 setActiveKeyPair 写入，退出登录 clearActiveKeyPair 清除）──
+
+  String? _activePublicKey;
+  String? _activePrivateKey;
+
   @override
   Future platformVersion() => _core.platform.getPlatformVersion();
 
@@ -93,6 +98,44 @@ class CipherGuardSdkApiImpl implements CipherGuardSdkApi {
     );
   }
 
+  @override
+  void setActiveKeyPair({
+    required String publicKey,
+    required String privateKey,
+  }) {
+    _activePublicKey = publicKey;
+    _activePrivateKey = privateKey;
+  }
+
+  @override
+  void clearActiveKeyPair() {
+    _activePublicKey = null;
+    _activePrivateKey = null;
+  }
+
+  @override
+  Future encryptSessionKeyWithActiveKey({required String sessionKey}) {
+    final key = _activePublicKey;
+    if (key == null) {
+      throw StateError('Active key pair not set. Call setActiveKeyPair first.');
+    }
+    return encryptSessionKey(sessionKey: sessionKey, publicKey: key);
+  }
+
+  @override
+  Future decryptSessionKeyWithActiveKey({
+    required String encryptedSessionKey,
+  }) {
+    final key = _activePrivateKey;
+    if (key == null) {
+      throw StateError('Active key pair not set. Call setActiveKeyPair first.');
+    }
+    return decryptSessionKey(
+      encryptedSessionKey: encryptedSessionKey,
+      privateKey: key,
+    );
+  }
+
   @override
   void clearDerivedKeyCache() => _core.encryptionRepo.clearDerivedKeyCache();
 

From 03b89706a5133b9a5f06f1a150e027ee781f0e49 Mon Sep 17 00:00:00 2001
From: Cody 
Date: Mon, 9 Mar 2026 11:04:52 +0800
Subject: [PATCH 5/5] =?UTF-8?q?=E6=9E=81=E7=AE=80=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=E5=AE=9A=E4=B9=89=E5=92=8C=E5=93=8D=E5=BA=94=E5=AE=9A=E4=B9=89?=
 =?UTF-8?q?=EF=BC=8C=E6=94=AF=E6=8C=81=E6=9B=B4=E5=A4=9A=E7=9A=84=E8=A7=A3?=
 =?UTF-8?q?=E6=9E=90=E5=99=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Doc/IM_App_架构设计.html                      | 214 ++++++++----------
 .../lib/data/remote/get_profile_request.dart  |  34 ++-
 .../im_app/lib/data/remote/login_request.dart |  49 ++--
 .../lib/data/remote/logout_request.dart       |  23 +-
 .../lib/data/remote/upload_file_request.dart  |   6 +-
 .../repositories/auth_repository_impl.dart    |  12 +-
 .../login/presentation/login_view_model.dart  |  36 ++-
 .../login/usecases/login_usecase.dart         |  22 +-
 packages/networks_sdk/lib/networks_sdk.dart   |   1 +
 .../lib/src/annotations/api_request.dart      |  43 ++--
 .../lib/src/annotations/api_response.dart     |  31 +++
 .../src/generator/api_request_generator.dart  |  52 +++--
 .../src/generator/api_response_generator.dart | 205 +++++++++++++++++
 .../lib/src/generator/builder.dart            |  15 +-
 14 files changed, 482 insertions(+), 261 deletions(-)
 create mode 100644 packages/networks_sdk/lib/src/annotations/api_response.dart
 create mode 100644 packages/networks_sdk/lib/src/generator/api_response_generator.dart

diff --git a/Doc/IM_App_架构设计.html b/Doc/IM_App_架构设计.html
index 12edacb..698760e 100644
--- a/Doc/IM_App_架构设计.html
+++ b/Doc/IM_App_架构设计.html
@@ -886,8 +886,9 @@ flowchart TD
 │           ├── annotations/
 │           │   └── api_request.dart        # @ApiRequest 注解定义
 │           ├── generator/
-│           │   ├── api_request_generator.dart  # build_runner 代码生成器实现
-│           │   └── builder.dart                # SharedPartBuilder 入口
+│           │   ├── api_request_generator.dart  # Request mixin 生成器（toJson / path / method / fromJson 注册）
+│           │   ├── api_response_generator.dart # Response fromJson 生成器（从 @ApiRequest(responseType) 自动推导，递归嵌套类型）
+│           │   └── builder.dart                # SharedPartBuilder 入口（两个生成器合并到同一 .g.dart）
 │           ├── data/
 │           │   ├── datasources/
 │           │   │   ├── http/
@@ -2286,23 +2287,21 @@ extension APIRequestableExtension<T> on APIRequestable<T> {
 
 
    一个端点 = 一个文件（data/remote/login_request.dart），Response DTO + Request 放在同一文件中。
    
 
-
    import 'package:json_annotation/json_annotation.dart';
-import 'package:networks_sdk/networks_sdk.dart';
+
    import 'package:networks_sdk/networks_sdk.dart';
 
 part 'login_request.g.dart';
 
-// ── Response DTO ──
+// ── Response DTO（纯 Dart 类，零注解，零样板）──
+// _$LoginResponseFromJson 由 ApiResponseGenerator 从 @ApiRequest(responseType: T) 自动推导生成
 
-@JsonSerializable()
-class LoginData {
+class LoginResponse {
   final String token;
-  @JsonKey(name: 'user_id')
+  @JsonKey(name: 'user_id')    // @JsonKey 由生成器读取，Response 类不需要 @JsonSerializable
   final String userId;
   final String email;
 
-  const LoginData({required this.token, required this.userId, required this.email});
-  factory LoginData.fromJson(Map<String, dynamic> json) => _$LoginDataFromJson(json);
-  Map<String, dynamic> toJson() => _$LoginDataToJson(this);
+  const LoginResponse({required this.token, required this.userId, required this.email});
+  // 无 factory fromJson — 生成器在 .g.dart 中提供私有 _$LoginResponseFromJson
 
   User toEntity() => User(id: userId, email: email); // DTO → Domain Entity
 }
@@ -2313,23 +2312,23 @@ class LoginData {
 @ApiRequest(
   path: ApiPaths.authLogin,                // 路径统一在 core/foundation/api_paths.dart 管理
   method: HttpMethod.post,
-  responseType: LoginData,
+  responseType: LoginResponse,
   requestType: ApiRequestType.login,
 )
-class LoginRequest extends ApiRequestable<LoginData> with _$LoginRequestApi {
+class LoginRequest extends ApiRequestable<LoginResponse> with _$LoginRequestApi {
   final String email;
   final String password;
 
   LoginRequest({required this.email, required this.password});
-  // 完毕！toJson 由 mixin 从类字段自动生成，fromJson 不需要（Request 永远手动构造）
+  // 完毕！toJson 由 mixin 从类字段自动生成，fromJson 注册也全部自动处理
 }
 
    
 
 
    // 使用 - 超级简单！
-final loginData = await apiClient.executeRequest(
+final loginResponse = await apiClient.executeRequest(
   LoginRequest(email: 'user@example.com', password: '123456'),
 );
-final user = loginData?.toEntity(); // DTO → Domain Entity
+final user = loginResponse?.toEntity(); // DTO → Domain Entity
 
    
 
 
    
@@ -2359,8 +2358,8 @@ final user = loginData?.toEntity(); // DTO → Domain Entity
 
 
 @ApiRequest（当前方案）
-字段 + 构造函数 + @ApiRequest
-path / method / requestType / includeToken / toJson / fromJson 注册
+字段 + 构造函数 + @ApiRequest
    （Response DTO：字段 + 构造函数，零注解）
+Request: path / method / requestType / includeToken / toJson / fromJson 注册
    Response: _$XFromJson 私有反序列化函数（按需递归生成嵌套类型）
 极低
 
 
@@ -2368,10 +2367,10 @@ final user = loginData?.toEntity(); // DTO → Domain Entity
 
 
    核心优势：
    
 
      
-
    • 注解驱动：@ApiRequest 一个注解自动生成 mixin（含 toJson），无需 @JsonSerializable
      • 
+
    • Request 零样板：@ApiRequest 一个注解生成 mixin（含 toJson），无需 @JsonSerializable
      • 
+
    • Response 零注解：Response DTO 不需要 @JsonSerializable，不需要 factory fromJson，_$XFromJson 由生成器从 @ApiRequest(responseType: T) 自动推导；嵌套自定义类型递归生成，依赖关系自动处理
      • 
 
    • 自动注册：fromJson 在首次请求时自动注册到全局注册表，无需手动 registerApiResponses()
      • 
 
    • 一个端点 = 一个文件：Response DTO + Request 放在同一文件，打开即看全貌
      • 
-
    • 傻瓜式使用：使用者只需关注业务字段和注解配置
      • 
 
    • 类型安全：ApiRequestable<T> 泛型 + responseType 编译期检查
      • 
 
    
 
@@ -2387,12 +2386,12 @@ final user = loginData?.toEntity(); // DTO → Domain Entity
 
 
 Swift
-struct LoginRequest: APIRequestable { typealias Response = LoginData ... }
+struct LoginRequest: APIRequestable { typealias Response = LoginResponse ... }
 协议直接实现，最简洁
 
 
 Dart
-@ApiRequest(...) class LoginRequest extends ApiRequestable<LoginData> with _$LoginRequestApi { ... }
+@ApiRequest(...) class LoginRequest extends ApiRequestable<LoginResponse> with _$LoginRequestApi { ... }
 注解 + 代码生成，接近 Swift 体验
 
 
@@ -2530,26 +2529,23 @@ melos run gen
 
 
    4.5 更多使用示例
    
 
-
    所有示例遵循同一模式：@ApiRequest + extends ApiRequestable<T> with _$XxxApi。Request 类无需 @JsonSerializable。
    
+
    所有示例遵循同一模式：@ApiRequest + extends ApiRequestable<T> with _$XxxApi。Request 和 Response 均无需 @JsonSerializable，Response DTO 连 factory fromJson 也不需要。
    
 
 
    发送消息请求（POST + @JsonKey 字段重命名）：
    
 
    // data/remote/send_message_request.dart
 
-// ── Response DTO（仍用 @JsonSerializable）──
-@JsonSerializable()
-class SendMessageData {
+// ── Response DTO（纯 Dart 类，零注解，_$SendMessageResponseFromJson 由生成器自动提供）──
+class SendMessageResponse {
   @JsonKey(name: 'message_id')
   final String messageId;
   final int timestamp;
 
-  const SendMessageData({required this.messageId, required this.timestamp});
-  factory SendMessageData.fromJson(Map<String, dynamic> json) =>
-      _$SendMessageDataFromJson(json);
+  const SendMessageResponse({required this.messageId, required this.timestamp});
 }
 
 // ── Request（零样板）──
-@ApiRequest(path: ApiPaths.chatSendMessage, responseType: SendMessageData)
-class SendMessageRequest extends ApiRequestable<SendMessageData>
+@ApiRequest(path: ApiPaths.chatSendMessage, responseType: SendMessageResponse)
+class SendMessageRequest extends ApiRequestable<SendMessageResponse>
     with _$SendMessageRequestApi {
   @JsonKey(name: 'chat_id')  // 生成器会读取，JSON 键名为 'chat_id'
   final String chatId;
@@ -2563,23 +2559,21 @@ class SendMessageRequest extends ApiRequestable<SendMessageData>
 
    获取用户资料（GET，靠 token 标识当前用户，无需传参）：
    
 
    // data/remote/get_profile_request.dart
 
-@JsonSerializable(createToJson: false)  // 只需反序列化
-class ProfileData {
+// ── Response DTO（纯 Dart 类，零注解，_$ProfileResponseFromJson 由生成器自动提供）──
+class ProfileResponse {
   @JsonKey(name: 'user_id')
   final String userId;
   final String email;
   final String? nickname;
   final String? avatar;
 
-  const ProfileData({required this.userId, required this.email, this.nickname, this.avatar});
-  factory ProfileData.fromJson(Map<String, dynamic> json) =>
-      _$ProfileDataFromJson(json);
+  const ProfileResponse({required this.userId, required this.email, this.nickname, this.avatar});
 
   User toEntity() => User(id: userId, email: email, nickname: nickname, avatar: avatar);
 }
 
-@ApiRequest(path: ApiPaths.userProfile, method: HttpMethod.get, responseType: ProfileData)
-class GetProfileRequest extends ApiRequestable<ProfileData>
+@ApiRequest(path: ApiPaths.userProfile, method: HttpMethod.get, responseType: ProfileResponse)
+class GetProfileRequest extends ApiRequestable<ProfileResponse>
     with _$GetProfileRequestApi {
   GetProfileRequest();  // 无参数 — toJson 自动生成空 map
 }
@@ -2588,14 +2582,12 @@ class GetProfileRequest extends ApiRequestable<ProfileData>
 
    上传文件请求（FormData multipart）：
    
 
    // data/remote/upload_file_request.dart
 
-@JsonSerializable()
+// ── Response DTO（纯 Dart 类，零注解，_$UploadResultFromJson 由生成器自动提供）──
 class UploadResult {
   final String url;
   @JsonKey(name: 'file_id')
   final String fileId;
   const UploadResult({required this.url, required this.fileId});
-  factory UploadResult.fromJson(Map<String, dynamic> json) =>
-      _$UploadResultFromJson(json);
 }
 
 @ApiRequest(
@@ -2624,7 +2616,8 @@ class UploadFileRequest extends ApiRequestable<UploadResult>
 
    
 
    核心价值
    
 
      
-
    • 极简使用：字段 + 构造函数 + @ApiRequest（Request 无需 @JsonSerializable、无需 fromJson、无需手写 toJson）
      • 
+
    • Request 极简：字段 + 构造函数 + @ApiRequest（无需 @JsonSerializable、无需手写 toJson）
      • 
+
    • Response 零注解：Response DTO 是纯 Dart 类，无需 @JsonSerializable，无需 factory fromJson，_$XFromJson 由生成器从 responseType 自动推导
      • 
 
    • 零维护：path / method / requestType / includeToken / toJson / fromJson 注册 全部自动生成
      • 
 
    • 类型安全：泛型 ApiRequestable<T> + responseType 编译期检查
      • 
 
    • 一个端点 = 一个文件：Response DTO + Request 放在同一文件，打开即看全貌
      • 
@@ -2721,11 +2714,11 @@ class LoginViewModel extends _$LoginViewModel {
           → LoggingInterceptor                   ← 请求/响应日志
         ← request.decodeResponse(response)       ← 自动解码
           ← ApiResponseWrapper.fromJson          ← 拆 { code, msg, data }
-          ← fromJsonRegistry[LoginData]          ← 查注册表
-          ← LoginData.fromJson(data)             ← 反序列化
-      ← LoginData（DTO）
+          ← fromJsonRegistry[LoginResponse]       ← 查注册表
+          ← _$LoginResponseFromJson(data)        ← 反序列化（生成的私有函数）
+      ← LoginResponse（DTO）
       → onTokenUpdate(token)                     ← 回调写入 Token（内存 + 持久化）
-      ← loginData.toEntity() → User              ← DTO → Domain Entity
+      ← loginResponse.toEntity() → User          ← DTO → Domain Entity
     ← User
   ← state.copyWith(user: user)                   ← 更新状态
 View: ref.watch → 自动 rebuild                    ← UI 刷新
@@ -5715,7 +5708,7 @@ class MessageLocalDataSource {
 class MessageRepositoryImpl implements MessageRepository {
   final NetworksSdkApi _client;
 
-  Future<SendMessageData?> sendMessage({
+  Future<SendMessageResponse?> sendMessage({
     required String chatId,
     required String content,
   }) {
@@ -5978,7 +5971,7 @@ flowchart LR
 层级文件命名类命名示例
 
 
-接口定义{action}_request.dartRequest: {Action}Request
      Response DTO: {Action}Datalogin_request.dart → LoginRequest + LoginData
+接口定义{action}_request.dartRequest: {Action}Request
      Response DTO: {Action}Responselogin_request.dart → LoginRequest + LoginResponse
 持久化 DTOdata/models/{entity}_dto.dart{Entity}Dtouser_dto.dart → UserDto
 Repository 接口domain/repositories/{module}_repository.dart{Module}Repositoryauth_repository.dart → AuthRepository
 Repository 实现data/repositories/{module}_repository_impl.dart{Module}RepositoryImplauth_repository_impl.dart → AuthRepositoryImpl
@@ -5990,8 +5983,8 @@ flowchart LR
 
      关键规则：
      
 
        
 
      • 一个端点 = 一个 Request 文件：Response DTO + Request 类放在同一文件中
        • 
-
      • Response DTO 必须有 toEntity()：统一 DTO → Domain Entity 的转换入口
        • 
-
      • 持久化 DTO 和 Response DTO 分开：Response DTO（XxxData）在 request 文件中，持久化 DTO（XxxDto）在 data/models/
        • 
+
      • Response DTO 是纯 Dart 类：零注解、零 factory fromJson；只需字段 + 构造函数，toEntity() 按需添加
        • 
+
      • 持久化 DTO 和 Response DTO 分开：Response DTO（XxxResponse）在 request 文件中，持久化 DTO（XxxDto）在 data/models/
        • 
 
      • 禁止跳层：ViewModel → Repository（→ UseCase 按需）→ NetworksSdkApi，每层职责明确
        • 
 
      
 
@@ -6041,8 +6034,10 @@ part 'login_request.g.dart';  // 这行必须写！指向即将自动生成的
 
      // ── Response DTO ──
 
 /// 服务端返回的登录数据
-@JsonSerializable()                       // ← 这个注解让 build_runner 自动生成 fromJson / toJson
-class LoginData {
+/// 纯 Dart 类，零注解，零样板。
+/// _$LoginResponseFromJson 由 ApiResponseGenerator 从 @ApiRequest(responseType: LoginResponse) 自动推导生成，
+/// 无需手动添加任何注解或 factory fromJson。
+class LoginResponse {
   final String token;                      // 服务端返回的字段
   @JsonKey(name: 'user_id')               // 服务端字段名是 user_id，Dart 字段名是 userId
   final String userId;
@@ -6050,18 +6045,15 @@ class LoginData {
   final String? nickname;                  // 可选字段用 String?
   final String? avatar;
 
-  const LoginData({                        // 构造函数，参数和字段一一对应
+  const LoginResponse({                    // 构造函数，参数和字段一一对应
     required this.token,
     required this.userId,
     required this.email,
     this.nickname,
     this.avatar,
   });
-
-  // ↓ 这两行是固定写法，照抄就行，把类名替换掉
-  factory LoginData.fromJson(Map<String, dynamic> json) =>
-      _$LoginDataFromJson(json);           // ← 短暂报红，watch 模式下保存后几秒自动消失
-  Map<String, dynamic> toJson() => _$LoginDataToJson(this);
+  // 不需要 factory fromJson，不需要 toJson，不需要任何注解
+  // 生成器自动在 login_request.g.dart 中生成 _$LoginResponseFromJson 私有函数
 
   /// DTO → Domain Entity（把网络层数据转为业务层数据）
   User toEntity() {
@@ -6103,19 +6095,16 @@ class LoginData {
 @ApiRequest(                               // ← 这个注解让 build_runner 自动生成 path / method 等
   path: ApiPaths.authLogin,                //    路径常量，定义在 core/foundation/api_paths.dart
   method: HttpMethod.post,                 //    HTTP 方法，从接口文档抄
-  responseType: LoginData,                 //    响应类型，就是上面写的 LoginData
+  responseType: LoginResponse,             //    响应类型，就是上面写的 LoginResponse
   requestType: ApiRequestType.login,       //    login 类型不携带 Token（登录前还没有 Token）
 )
-@JsonSerializable()                        // ← 自动生成 toJson（把请求参数序列化为 JSON）
-class LoginRequest extends ApiRequestable<LoginData>  // ← 固定写法：extends ApiRequestable<响应类型>
-    with _$LoginRequestApi {                           // ← 固定写法：with _$类名Api（短暂报红，保存后自动消失）
+class LoginRequest extends ApiRequestable<LoginResponse>  // ← 固定写法：extends ApiRequestable<响应类型>
+    with _$LoginRequestApi {                              // ← 固定写法：with _$类名Api（短暂报红，保存后自动消失）
   final String email;                      // 请求参数：要发给服务端的字段
   final String password;
 
   LoginRequest({required this.email, required this.password});
-
-  @override
-  Map<String, dynamic> toJson() => _$LoginRequestToJson(this);  // ← 固定写法，短暂报红，保存后自动消失
+  // 完毕！toJson 由 _$LoginRequestApi mixin 从类字段自动生成，不需要 @JsonSerializable，不需要手写 toJson
 }
 
      
 
@@ -6124,14 +6113,14 @@ class LoginRequest extends ApiRequestable<LoginData>  // ← 固定写法
 
      
 
      命名规则速查（写之前就能确定引用名）
      
 
-
+
-
-
-
+
+
+
      你写的类名fromJsontoJsonApi mixin
      你写的类名fromJson（私有函数）toJsonApi mixin来源
      
 
      LoginData_$LoginDataFromJson_$LoginDataToJson-
      LoginRequest_$LoginRequestFromJson_$LoginRequestToJson_$LoginRequestApi
      SendMessageRequest_$SendMessageRequestFromJson_$SendMessageRequestToJson_$SendMessageRequestApi
      LoginResponse_$LoginResponseFromJson-（不需要）-ApiResponseGenerator 自动推导
      LoginRequest-（不需要）由 mixin 自动生成_$LoginRequestApiApiRequestGenerator 生成 mixin
      SendMessageRequest-（不需要）由 mixin 自动生成_$SendMessageRequestApiApiRequestGenerator 生成 mixin
      
       
 
      
-
      规则：_$ + 类名 + FromJson / ToJson / Api。固定前缀，直接拼。
      
+
      规则：Response DTO 类名拼 _$ + 类名 + FromJson（私有，只在 .g.dart 内部使用）；Request 类名拼 _$ + 类名 + Api（mixin）。
      
 
      
 
 
@@ -6162,19 +6151,19 @@ class AuthRepositoryImpl implements AuthRepository {
     required String password,
   }) async {
     // 1. 调 NetworksSdkApi，构造请求 → 发 HTTP → 自动解码 → 返回 DTO
-    final LoginData? loginData = await _client.executeRequest(
+    final LoginResponse? loginResponse = await _client.executeRequest(
       LoginRequest(email: email, password: password),
     );
 
-    if (loginData == null) {
+    if (loginResponse == null) {
       throw Exception('Login failed: empty response');
     }
 
     // 2. 回调写入 Token（内存 + 持久化由 Provider 层组合）
-    _onTokenUpdate(loginData.token);
+    _onTokenUpdate(loginResponse.token);
 
     // 3. DTO → Domain Entity，返回给上层
-    return loginData.toEntity();
+    return loginResponse.toEntity();
   }
 }
 
    
@@ -6321,10 +6310,10 @@ class LoginViewModel extends _$LoginViewModel {
         → AuthRepositoryImpl.login()                               // data/repositories/
           → _client.executeRequest(LoginRequest)                   // 调 NetworksSdkApi
             → Auth → Encryption → Dio.request → Retry → Logging // 拦截器链自动处理
-          ← request.decodeResponse → LoginData.fromJson           // 自动解码
-        ← LoginData（DTO）
+          ← request.decodeResponse → _$LoginResponseFromJson      // 自动解码（生成的私有函数）
+        ← LoginResponse（DTO）
         → onTokenUpdate(token)                                    // 回调：内存写入 + 持久化
-        ← loginData.toEntity() → User（Domain Entity）
+        ← loginResponse.toEntity() → User（Domain Entity）
       ← User
     ← state = state.copyWith(user: user)                         // 更新状态
   ← View: ref.watch → 自动 rebuild → UI 显示用户信息              // 自动刷新
@@ -6345,22 +6334,18 @@ class LoginViewModel extends _$LoginViewModel {
 
 
    你只需创建一个文件：lib/data/remote/send_message_request.dart，然后在 Repository 中调用即可。
    
 
-
    import 'package:json_annotation/json_annotation.dart';
-import 'package:networks_sdk/networks_sdk.dart';
+
    import 'package:networks_sdk/networks_sdk.dart';
 
 part 'send_message_request.g.dart';
 
-// ── Response DTO ──
+// ── Response DTO（纯 Dart 类，零注解，_$SendMessageResponseFromJson 由生成器自动提供）──
 
-@JsonSerializable()
-class SendMessageData {
+class SendMessageResponse {
   @JsonKey(name: 'message_id')
   final String messageId;
   final int timestamp;
 
-  const SendMessageData({required this.messageId, required this.timestamp});
-  factory SendMessageData.fromJson(Map<String, dynamic> json) =>
-      _$SendMessageDataFromJson(json);
+  const SendMessageResponse({required this.messageId, required this.timestamp});
 }
 
 // ── Request ──
@@ -6368,26 +6353,24 @@ class SendMessageData {
 @ApiRequest(
   path: ApiPaths.chatSendMessage,           // 路径常量，定义在 api_paths.dart
   method: HttpMethod.post,                 // HTTP 方法
-  responseType: SendMessageData,           // 响应类型
+  responseType: SendMessageResponse,       // 响应类型
   // requestType 不写，默认 ApiRequestType.request（会携带 Token）
 )
-@JsonSerializable()
-class SendMessageRequest extends ApiRequestable<SendMessageData>
+class SendMessageRequest extends ApiRequestable<SendMessageResponse>
     with _$SendMessageRequestApi {
   @JsonKey(name: 'chat_id')               // JSON 字段名和 Dart 字段名不一样时用 @JsonKey
   final String chatId;
   final String content;
 
   SendMessageRequest({required this.chatId, required this.content});
-  @override
-  Map<String, dynamic> toJson() => _$SendMessageRequestToJson(this);
+  // toJson 自动生成：{'chat_id': chatId, 'content': content}
 }
 
    
 
 
    保存 → 自动生成 → 然后在 Repository 中调 NetworksSdkApi 就完了：
    
 
 
    // 在 MessageRepositoryImpl 中添加
-Future<SendMessageData?> sendMessage({
+Future<SendMessageResponse?> sendMessage({
   required String chatId,
   required String content,
 }) {
@@ -6407,22 +6390,19 @@ Future<SendMessageData?> sendMessage({
 
 
    // lib/data/remote/get_profile_request.dart
 
-import 'package:json_annotation/json_annotation.dart';
 import 'package:networks_sdk/networks_sdk.dart';
 
 part 'get_profile_request.g.dart';
 
-@JsonSerializable()
-class ProfileData {
+// ── Response DTO（纯 Dart 类，零注解，_$ProfileResponseFromJson 由生成器自动提供）──
+class ProfileResponse {
   @JsonKey(name: 'user_id')
   final String userId;
   final String email;
   final String? nickname;
   final String? avatar;
 
-  const ProfileData({required this.userId, required this.email, this.nickname, this.avatar});
-  factory ProfileData.fromJson(Map<String, dynamic> json) =>
-      _$ProfileDataFromJson(json);
+  const ProfileResponse({required this.userId, required this.email, this.nickname, this.avatar});
 
   User toEntity() => User(id: userId, email: email, nickname: nickname, avatar: avatar);
 }
@@ -6430,15 +6410,12 @@ class ProfileData {
 @ApiRequest(
   path: ApiPaths.userProfile,
   method: HttpMethod.get,                  // ← GET 请求，toJson() 结果作为 query string
-  responseType: ProfileData,
+  responseType: ProfileResponse,
 )
-@JsonSerializable()
-class GetProfileRequest extends ApiRequestable<ProfileData>
+class GetProfileRequest extends ApiRequestable<ProfileResponse>
     with _$GetProfileRequestApi {
   GetProfileRequest();  // 无参数 — token 标识当前用户，无需显式传 user_id
-
-  @override
-  Map<String, dynamic> toJson() => _$GetProfileRequestToJson(this);
+  // toJson 自动生成空 map {}
 }
 
    
 
@@ -6685,41 +6662,33 @@ melos run gen:watch
 
 
    // data/remote/login_request.dart
 
-import 'package:json_annotation/json_annotation.dart';
 import 'package:networks_sdk/networks_sdk.dart';
 
 part 'login_request.g.dart';  // ← 必须写，指向即将生成的文件
 
-// ── Response DTO ──
-@JsonSerializable()
-class LoginData {
+// ── Response DTO（纯 Dart 类，零注解，零样板）──
+// _$LoginResponseFromJson 由 ApiResponseGenerator 从 @ApiRequest(responseType: LoginResponse) 自动推导生成
+class LoginResponse {
   final String token;
   final String email;
-  const LoginData({required this.token, required this.email});
-
-  // ↓ 此时 _$LoginDataFromJson 还不存在，IDE 会报红，正常！
-  factory LoginData.fromJson(Map<String, dynamic> json) =>
-      _$LoginDataFromJson(json);
-  Map<String, dynamic> toJson() => _$LoginDataToJson(this);
+  const LoginResponse({required this.token, required this.email});
+  // 不需要 factory fromJson，不需要任何注解
 }
 
 // ── Request ──
 @ApiRequest(
   path: ApiPaths.authLogin,
   method: HttpMethod.post,
-  responseType: LoginData,
+  responseType: LoginResponse,
   requestType: ApiRequestType.login,
 )
-@JsonSerializable()
-class LoginRequest extends ApiRequestable<LoginData>
+class LoginRequest extends ApiRequestable<LoginResponse>
     with _$LoginRequestApi {                // ← 短暂报红，保存后自动消失
   final String email;
   final String password;
 
   LoginRequest({required this.email, required this.password});
-
-  @override
-  Map<String, dynamic> toJson() => _$LoginRequestToJson(this);  // ← 短暂报红，保存后自动消失
+  // toJson 由 mixin 自动生成，保存后红线自动消失
 }
 
    
 
@@ -6734,11 +6703,10 @@ class LoginRequest extends ApiRequestable<LoginData>
 
    命名规则（写之前就能确定引用名）
    
 
 
-
+
-
-
-
+
+
    注解生成的符号示例
    来源生成的符号示例
    
 
    @JsonSerializable()_$类名FromJson()_$LoginDataFromJson(json)
    @JsonSerializable()_$类名ToJson()_$LoginDataToJson(this)
    @ApiRequest(...)_$类名Api（mixin）_$LoginRequestApi
    @ApiRequest(responseType: T)
    （ApiResponseGenerator 推导）    		_$类名FromJson（私有函数，.g.dart 内部使用）_$LoginResponseFromJson(json)
    @ApiRequest(...) on Request 类
    （ApiRequestGenerator 生成 mixin）    		_$类名Api（mixin）_$LoginRequestApi
    
     
 
    
 
diff --git a/apps/im_app/lib/data/remote/get_profile_request.dart b/apps/im_app/lib/data/remote/get_profile_request.dart
index c51ed81..5030fec 100644
--- a/apps/im_app/lib/data/remote/get_profile_request.dart
+++ b/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 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
+class GetProfileRequest extends ApiRequestable
     with _$GetProfileRequestApi {
   GetProfileRequest();
 }
diff --git a/apps/im_app/lib/data/remote/login_request.dart b/apps/im_app/lib/data/remote/login_request.dart
index 9d1c976..b8b18a7 100644
--- a/apps/im_app/lib/data/remote/login_request.dart
+++ b/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  ← 也在这里
+///         → 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 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`）。
+///
+/// `{ 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 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 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,
diff --git a/apps/im_app/lib/data/remote/logout_request.dart b/apps/im_app/lib/data/remote/logout_request.dart
index a4a908d..651f940 100644
--- a/apps/im_app/lib/data/remote/logout_request.dart
+++ b/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 {
-  @override
-  String get path => ApiPaths.authLogout;
-
-  @override
-  HttpMethod get method => HttpMethod.post;
-
-  /// 登出不需要请求体参数
-  @override
-  Map toJson() => {};
+@ApiRequest(path: ApiPaths.authLogout, method: HttpMethod.post)
+class LogoutRequest extends ApiRequestable with _$LogoutRequestApi {
+  LogoutRequest();
 }
diff --git a/apps/im_app/lib/data/remote/upload_file_request.dart b/apps/im_app/lib/data/remote/upload_file_request.dart
index abb4440..7917ca4 100644
--- a/apps/im_app/lib/data/remote/upload_file_request.dart
+++ b/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 json) =>
-      _$UploadResultFromJson(json);
 }
 
 // ═════════════════════════════════════════════
diff --git a/apps/im_app/lib/data/repositories/auth_repository_impl.dart b/apps/im_app/lib/data/repositories/auth_repository_impl.dart
index 0c167cb..afdec66 100644
--- a/apps/im_app/lib/data/repositories/auth_repository_impl.dart
+++ b/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();
   }
diff --git a/apps/im_app/lib/features/login/presentation/login_view_model.dart b/apps/im_app/lib/features/login/presentation/login_view_model.dart
index 7552100..2cf2b45 100644
--- a/apps/im_app/lib/features/login/presentation/login_view_model.dart
+++ b/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;
-      final loginResponse = LoginResponse.fromJson(json);
-      final user = loginResponse.data.toEntity();
+      final data = json['data'] as Map;
+      final profile = data['profile'] as Map;
+      // 生成器生成的 _$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);
diff --git a/apps/im_app/lib/features/login/usecases/login_usecase.dart b/apps/im_app/lib/features/login/usecases/login_usecase.dart
index 493ef42..68e76f5 100644
--- a/apps/im_app/lib/features/login/usecases/login_usecase.dart
+++ b/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，
diff --git a/packages/networks_sdk/lib/networks_sdk.dart b/packages/networks_sdk/lib/networks_sdk.dart
index 5e2405a..b514681 100644
--- a/packages/networks_sdk/lib/networks_sdk.dart
+++ b/packages/networks_sdk/lib/networks_sdk.dart
@@ -29,3 +29,4 @@ export 'src/domain/entities/socket_error.dart';
 
 // Annotations（代码生成）
 export 'src/annotations/api_request.dart';
+export 'src/annotations/api_response.dart';
diff --git a/packages/networks_sdk/lib/src/annotations/api_request.dart b/packages/networks_sdk/lib/src/annotations/api_request.dart
index 50a3b23..1fe3204 100644
--- a/packages/networks_sdk/lib/src/annotations/api_request.dart
+++ b/packages/networks_sdk/lib/src/annotations/api_request.dart
@@ -1,49 +1,56 @@
 import 'package:networks_sdk/src/domain/entities/api_request_type.dart';
 import 'package:networks_sdk/src/domain/entities/http_method.dart';
 
-
 /// API 请求注解 — 标记一个类为 API 请求
 ///
 /// 配合 `build_runner` 代码生成器，自动生成 `ApiRequestable` 协议实现，
 /// 使用侧只需定义字段 + 注解，path / method / requestType / includeToken
 /// 全部由生成器自动提供。
 ///
-/// ## 使用方式
+/// ## 有响应数据（指定 responseType）
 ///
 /// ```dart
 /// @ApiRequest(
-///   path: '/auth/login',
+///   path: ApiPaths.authLogin,
 ///   method: HttpMethod.post,
-///   responseType: LoginData,
+///   responseType: LoginResponse,
 ///   requestType: ApiRequestType.login,
 /// )
-/// @JsonSerializable()
-/// class LoginRequest extends ApiRequestable
+/// class LoginRequest extends ApiRequestable
 ///     with _$LoginRequestApi {
 ///   final String email;
 ///   final String password;
 ///
 ///   LoginRequest({required this.email, required this.password});
-///
-///   @override
-///   Map toJson() => _$LoginRequestToJson(this);
 /// }
 /// ```
 ///
-/// 生成器自动生成 `_$LoginRequestApi` mixin，提供：
-/// - `path` → `'/auth/login'`
-/// - `method` → `HttpMethod.post`
-/// - `requestType` → `ApiRequestType.login`
-/// - `includeToken` → `false`（login 类型自动设为 false）
+/// ## 无响应数据（省略 responseType）
+///
+/// ```dart
+/// @ApiRequest(
+///   path: ApiPaths.authLogout,
+///   method: HttpMethod.post,
+/// )
+/// class LogoutRequest extends ApiRequestable
+///     with _$LogoutRequestApi {
+///   LogoutRequest();
+/// }
+/// ```
+///
+/// 生成器自动生成 `_$XxxRequestApi` mixin，提供：
+/// - `path` / `method` / `requestType` / `includeToken`
+/// - `toJson()` — 从声明字段自动生成
+/// - `responseType` 存在时：`parameters` getter 自动注册 `fromJson`
 class ApiRequest {
-  /// API 路径（如 `'/auth/login'`）
+  /// API 路径（如 `ApiPaths.authLogin`）
   final String path;
 
   /// HTTP 方法（默认 POST）
   final HttpMethod method;
 
-  /// 响应类型（用于泛型绑定）
-  final Type responseType;
+  /// 响应数据类型（省略表示无响应数据，对应 `ApiRequestable`）
+  final Type? responseType;
 
   /// 请求类型（决定 header 处理方式，默认 request）
   final ApiRequestType requestType;
@@ -57,7 +64,7 @@ class ApiRequest {
   const ApiRequest({
     required this.path,
     this.method = HttpMethod.post,
-    required this.responseType,
+    this.responseType,
     this.requestType = ApiRequestType.request,
     this.includeToken,
     this.customHeaders,
diff --git a/packages/networks_sdk/lib/src/annotations/api_response.dart b/packages/networks_sdk/lib/src/annotations/api_response.dart
new file mode 100644
index 0000000..27f195c
--- /dev/null
+++ b/packages/networks_sdk/lib/src/annotations/api_response.dart
@@ -0,0 +1,31 @@
+/// Response DTO 无需任何注解。
+///
+/// 生成器从 `@ApiRequest(responseType: T)` 声明出发，自动推导并生成
+/// `_$TFromJson` 反序列化函数，以及所有嵌套自定义类型的 `fromJson`。
+///
+/// ## 使用方式（只需标注 Request 类）
+///
+/// ```dart
+/// // Request：唯一需要注解的地方
+/// @ApiRequest(path: ApiPaths.authLogin, responseType: LoginResponse)
+/// class LoginRequest extends ApiRequestable
+///     with _$LoginRequestApi {
+///   final String email;
+///   final String password;
+///   LoginRequest({required this.email, required this.password});
+/// }
+///
+/// // Response：纯 Dart 类，零注解，零样板
+/// class LoginResponse {
+///   @JsonKey(name: 'access_token') final String accessToken;
+///   final LoginProfile profile;
+///   const LoginResponse({required this.accessToken, required this.profile});
+///   // 生成器自动提供 _$LoginResponseFromJson
+/// }
+/// ```
+///
+/// 此文件保留作占位符，供未来扩展使用（如自定义序列化策略）。
+/// 当前版本 Response 类无需标注任何注解，所有 fromJson 由生成器自动推导。
+class ApiResponse {
+  const ApiResponse();
+}
diff --git a/packages/networks_sdk/lib/src/generator/api_request_generator.dart b/packages/networks_sdk/lib/src/generator/api_request_generator.dart
index d8592be..d6863ac 100644
--- a/packages/networks_sdk/lib/src/generator/api_request_generator.dart
+++ b/packages/networks_sdk/lib/src/generator/api_request_generator.dart
@@ -20,25 +20,36 @@ const _jsonKeyChecker = TypeChecker.fromUrl(
 /// 支持 `@JsonKey(name: '...')` 字段重命名。
 /// 如有 `@JsonKey(includeToJson: false)` 则跳过该字段。
 ///
-/// ## 使用模式
-///
-/// Request 类只需 `@ApiRequest` 注解，无需 `@JsonSerializable`：
+/// ## 使用模式（有响应数据）
 ///
 /// ```dart
 /// @ApiRequest(
 ///   path: ApiPaths.authLogin,
 ///   method: HttpMethod.post,
-///   responseType: LoginData,
+///   responseType: LoginResponse,
 ///   requestType: ApiRequestType.login,
 /// )
-/// class LoginRequest extends ApiRequestable
+/// class LoginRequest extends ApiRequestable
 ///     with _$LoginRequestApi {
 ///   final String email;
 ///   final String password;
 ///
 ///   LoginRequest({required this.email, required this.password});
-///   // 完毕！toJson / path / method 全部由 mixin 自动生成
-///   // Response 的 fromJson 在 parameters getter 中自动注册
+///   // 完毕！toJson / path / method / fromJson 注册全部由 mixin 自动生成
+/// }
+/// ```
+///
+/// ## 使用模式（无响应数据）
+///
+/// ```dart
+/// @ApiRequest(
+///   path: ApiPaths.authLogout,
+///   method: HttpMethod.post,
+/// )
+/// class LogoutRequest extends ApiRequestable
+///     with _$LogoutRequestApi {
+///   LogoutRequest();
+///   // responseType 省略 → mixin 跳过 fromJson 注册
 /// }
 /// ```
 ///
@@ -46,10 +57,10 @@ const _jsonKeyChecker = TypeChecker.fromUrl(
 ///
 /// `_$Api`
 ///
-/// ## 生成示例
+/// ## 生成示例（有响应数据）
 ///
 /// ```dart
-/// mixin _$LoginRequestApi on ApiRequestable {
+/// mixin _$LoginRequestApi on ApiRequestable {
 ///   @override String get path => '/auth/login';
 ///   @override HttpMethod get method => HttpMethod.post;
 ///   @override ApiRequestType get requestType => ApiRequestType.login;
@@ -61,7 +72,7 @@ const _jsonKeyChecker = TypeChecker.fromUrl(
 ///   };
 ///   @override
 ///   Map? get parameters {
-///     registerResponse(LoginData.fromJson);
+///     registerResponse(_$LoginResponseFromJson);
 ///     return super.parameters;
 ///   }
 /// }
@@ -94,9 +105,13 @@ class ApiRequestGenerator extends GeneratorForAnnotation {
       'post',
     );
 
-    // 读取 responseType（用于泛型绑定 + 自动注册 fromJson）
-    final responseType = annotation.read('responseType').typeValue;
-    final responseTypeName = responseType.getDisplayString();
+    // 读取 responseType（可选：null 表示 void 响应，无需注册 fromJson）
+    final responseTypePeek = annotation.peek('responseType');
+    final bool hasResponseType =
+        responseTypePeek != null && !responseTypePeek.isNull;
+    final String responseTypeName = hasResponseType
+        ? responseTypePeek.typeValue.getDisplayString()
+        : 'void';
 
     // 读取 ApiRequestType 枚举值
     final requestTypeName = _readEnumName(
@@ -116,6 +131,14 @@ class ApiRequestGenerator extends GeneratorForAnnotation {
     // 从类的声明字段生成 toJson()
     final toJsonBody = _buildToJsonBody(element, className);
 
+    // 有响应类型：parameters getter 中注册 fromJson（使用生成的私有函数）
+    // ApiResponseGenerator 在同一 .g.dart 中生成 _$XFromJson，同 library 可访问
+    // 无响应类型（void）：跳过注册，直接返回 super.parameters
+    final parametersBody = hasResponseType
+        ? '''  registerResponse<$responseTypeName>(_\$${responseTypeName}FromJson);
+    return super.parameters;'''
+        : '    return super.parameters;';
+
     return '''
 /// Generated by @ApiRequest for [$className]
 mixin _\$${className}Api on ApiRequestable<$responseTypeName> {
@@ -131,8 +154,7 @@ mixin _\$${className}Api on ApiRequestable<$responseTypeName> {
   Map toJson() => $toJsonBody;
   @override
   Map? get parameters {
-    registerResponse<$responseTypeName>($responseTypeName.fromJson);
-    return super.parameters;
+$parametersBody
   }
 }
 ''';
diff --git a/packages/networks_sdk/lib/src/generator/api_response_generator.dart b/packages/networks_sdk/lib/src/generator/api_response_generator.dart
new file mode 100644
index 0000000..946b920
--- /dev/null
+++ b/packages/networks_sdk/lib/src/generator/api_response_generator.dart
@@ -0,0 +1,205 @@
+import 'package:analyzer/dart/element/element.dart';
+import 'package:analyzer/dart/element/nullability_suffix.dart';
+import 'package:analyzer/dart/element/type.dart';
+import 'package:source_gen/source_gen.dart';
+import 'package:build/build.dart';
+
+/// @JsonKey 检测器（与 ApiRequestGenerator 共用相同策略）
+const _jsonKeyChecker = TypeChecker.fromUrl(
+  'package:json_annotation/src/json_key.dart#JsonKey',
+);
+
+/// @ApiRequest 检测器（复用，用于找到所有 responseType 入口）
+const _apiRequestChecker = TypeChecker.fromUrl(
+  'package:networks_sdk/src/annotations/api_request.dart#ApiRequest',
+);
+
+/// Response 反序列化代码生成器
+///
+/// 从同一 library 中的 `@ApiRequest(responseType: T)` 声明出发，
+/// 自动生成 `_$TFromJson` 私有函数，无需在 Response 类上添加任何注解。
+///
+/// ## 设计原理
+///
+/// App 层只需标注 Request 类：
+/// ```dart
+/// @ApiRequest(path: '...', responseType: LoginResponse)
+/// class LoginRequest extends ApiRequestable
+///     with _$LoginRequestApi { ... }
+/// ```
+///
+/// 生成器从 `responseType` 出发，递归找到所有嵌套自定义类型，
+/// 在同一 `.g.dart` 中生成所有 `_$XFromJson` 私有函数。
+///
+/// Response 类体本身是纯 Dart 类，**无需任何注解，无需 factory fromJson**：
+/// ```dart
+/// class LoginResponse {
+///   @JsonKey(name: 'access_token')
+///   final String accessToken;
+///   final LoginProfile profile;
+///   // 完毕！fromJson 由生成器自动提供
+/// }
+/// ```
+///
+/// ## 生成示例
+///
+/// ```dart
+/// LoginProfile _$LoginProfileFromJson(Map json) {
+///   return LoginProfile(
+///     uid: json['uid'] as int,
+///     uuid: json['uuid'] as String,
+///   );
+/// }
+///
+/// LoginResponse _$LoginResponseFromJson(Map json) {
+///   return LoginResponse(
+///     accessToken: json['access_token'] as String,
+///     profile: _$LoginProfileFromJson(json['profile'] as Map),
+///   );
+/// }
+/// ```
+///
+/// ## 支持的字段类型
+///
+/// - 基础类型（String / int / bool / double / num）
+/// - 可空类型（String? / int? / 自定义类?）
+/// - 嵌套对象（自动递归，在同一 `.g.dart` 中生成被依赖类的函数）
+/// - `@JsonKey(name: '...')` 字段重命名
+/// - `@JsonKey(includeFromJson: false)` 跳过字段
+class ApiResponseGenerator extends Generator {
+  @override
+  String generate(LibraryReader library, BuildStep buildStep) {
+    final buffer = StringBuffer();
+    // 跟踪已生成的类，避免同一 library 中多个 Request 引用同一 Response 类时重复生成
+    final generated = {};
+
+    for (final annotated in library.annotatedWith(_apiRequestChecker)) {
+      final annotation = annotated.annotation;
+      final responseTypePeek = annotation.peek('responseType');
+      if (responseTypePeek == null || responseTypePeek.isNull) continue;
+
+      final responseType = responseTypePeek.typeValue;
+      if (responseType is! InterfaceType) continue;
+
+      final responseClass = responseType.element;
+      if (responseClass is! ClassElement) continue;
+
+      // 只生成属于当前 library 的类（跨包类型跳过）
+      if (responseClass.library != library.element) continue;
+
+      _generateRecursive(responseClass, library, generated, buffer);
+    }
+
+    return buffer.toString();
+  }
+
+  /// 递归生成：先生成被依赖的嵌套类型，再生成当前类型（保证引用顺序）
+  void _generateRecursive(
+    ClassElement element,
+    LibraryReader library,
+    Set generated,
+    StringBuffer buffer,
+  ) {
+    final typeName = element.name!;
+    if (generated.contains(typeName)) return;
+    generated.add(typeName);
+
+    // 先递归处理嵌套的自定义类型
+    // InterfaceType 的 element 在 nullable 和非 nullable 情况下指向同一个 ClassElement
+    for (final field in element.fields.where(
+      (f) => !f.isStatic && !f.isSynthetic,
+    )) {
+      final fieldType = field.type;
+      if (fieldType is InterfaceType) {
+        final fieldClass = fieldType.element;
+        if (fieldClass is ClassElement &&
+            fieldClass.library == library.element &&
+            !_isPrimitive(fieldClass.name!)) {
+          _generateRecursive(fieldClass, library, generated, buffer);
+        }
+      }
+    }
+
+    final params = _buildConstructorParams(element);
+    buffer.write('''
+/// Generated by ApiResponseGenerator for [$typeName]
+$typeName _\$${typeName}FromJson(Map json) {
+  return $typeName(
+$params  );
+}
+''');
+  }
+
+  /// 判断是否为不需要递归生成的基础类型
+  bool _isPrimitive(String typeName) {
+    const primitives = {
+      'String',
+      'int',
+      'double',
+      'bool',
+      'num',
+      'dynamic',
+      'Object',
+      'List',
+      'Map',
+      'Set',
+      'Iterable',
+    };
+    return primitives.contains(typeName);
+  }
+
+  /// 从类的字段生成构造函数参数列表
+  String _buildConstructorParams(ClassElement element) {
+    final fields = element.fields
+        .where((f) => !f.isStatic && !f.isSynthetic)
+        .toList();
+
+    final lines = [];
+    for (final field in fields) {
+      final jsonKeyAnnotation = _jsonKeyChecker.firstAnnotationOfExact(field);
+
+      // @JsonKey(includeFromJson: false) → 跳过
+      final includeFromJson = jsonKeyAnnotation
+          ?.getField('includeFromJson')
+          ?.toBoolValue();
+      if (includeFromJson == false) continue;
+
+      final fieldName = field.name!;
+      final jsonName =
+          jsonKeyAnnotation?.getField('name')?.toStringValue() ?? fieldName;
+
+      final type = field.type;
+      final isNullable = type.nullabilitySuffix == NullabilitySuffix.question;
+      final expr = _castExpression(type, jsonName, isNullable);
+
+      lines.add('    $fieldName: $expr,');
+    }
+
+    return lines.join('\n');
+  }
+
+  /// 根据字段类型生成 JSON 取值表达式
+  String _castExpression(DartType type, String jsonKey, bool isNullable) {
+    final q = isNullable ? '?' : '';
+    final access = "json['$jsonKey']";
+
+    // 基础类型：直接 as 转换
+    if (type.isDartCoreString) return '$access as String$q';
+    if (type.isDartCoreInt) return '$access as int$q';
+    if (type.isDartCoreBool) return '$access as bool$q';
+    if (type.isDartCoreDouble) return '$access as double$q';
+    if (type.isDartCoreNum) return '$access as num$q';
+
+    // 嵌套对象：调用同一 part 文件中生成的 _$TypeFromJson 私有函数
+    if (type is InterfaceType) {
+      final typeName = type.element.name!;
+      if (isNullable) {
+        return '$access == null ? null : _\$${typeName}FromJson($access as Map)';
+      }
+      return '_\$${typeName}FromJson($access as Map)';
+    }
+
+    // 兜底
+    return '$access as dynamic';
+  }
+}
diff --git a/packages/networks_sdk/lib/src/generator/builder.dart b/packages/networks_sdk/lib/src/generator/builder.dart
index 0c91ae3..d3f64b4 100644
--- a/packages/networks_sdk/lib/src/generator/builder.dart
+++ b/packages/networks_sdk/lib/src/generator/builder.dart
@@ -2,11 +2,16 @@ import 'package:build/build.dart';
 import 'package:source_gen/source_gen.dart';
 
 import 'api_request_generator.dart';
+import 'api_response_generator.dart';
 
-/// @ApiRequest 代码生成器入口
+/// @ApiRequest / @ApiResponse 代码生成器入口
 ///
 /// 在 `build.yaml` 中注册此 builder，配合 `build_runner` 使用。
-/// 生成的代码通过 `SharedPartBuilder` 合并到 `.g.dart` 文件中，
-/// 与 `json_serializable` 等生成器共存。
-Builder apiRequestBuilder(BuilderOptions options) =>
-    SharedPartBuilder([ApiRequestGenerator()], 'api_request');
+/// 生成的代码通过 `SharedPartBuilder` 合并到 `.g.dart` 文件中。
+///
+/// - `ApiRequestGenerator`：为 `@ApiRequest` 生成 Request mixin（toJson + path/method 等）
+/// - `ApiResponseGenerator`：从 `@ApiRequest(responseType: T)` 推导，生成 Response 的所有 `_$XFromJson` 函数
+Builder apiRequestBuilder(BuilderOptions options) => SharedPartBuilder([
+  ApiRequestGenerator(),
+  ApiResponseGenerator(),
+], 'api_request');