customer-im-client-dev/Doc/mine_tab_architecture.md

我的（Mine）Tab — 架构文档

对应 Gitea issues #5–#13 参考实现：im-client-ios-swift-demo Features/Settings + Features/Profile

---

1. 功能范围

Issue	功能	状态
#5	Tab 重命名 & 个人资料卡片	✅ 已实现
#6	编辑个人资料（昵称/bio/头像）	✅ 框架已建（CDN 上传待 #6 后续）
#7	退出登录	✅ 已实现
#8	主题持久化	⏳ TODO（解开 ThemeModeNotifier 注释）
#9	语言设置	✅ UI 框架（l10n_sdk 待接入）
#10	黑名单管理	✅ 页面框架（API 待实现）
#11	聊天文件夹	⏳ TODO stub
#12	网络诊断	✅ 已实现（4步诊断）
#13	关于 / 版本	✅ 已实现

---

2. 目录结构

features/settings/
├── di/
│   └── settings_providers.dart      # UseCase DI 装配
├── presentation/
│   ├── settings_view_model.dart      # 我的页 ViewModel (NotifierProvider)
│   ├── edit_profile_view_model.dart  # 编辑资料 ViewModel
│   ├── network_diagnostics_view_model.dart  # 网络诊断 ViewModel
│   └── theme_view_model.dart         # 主题 ViewModel (@riverpod)
├── usecases/
│   ├── fetch_profile_usecase.dart    # GET /app/api/user/profile
│   ├── update_profile_usecase.dart   # POST /app/api/user/update-profile
│   ├── logout_usecase.dart           # POST /app/api/auth/logout + WS + DB
│   └── set_theme_usecase.dart        # 幂等主题切换
└── view/
    ├── settings_page.dart            # 我的主页
    ├── edit_profile_page.dart        # 编辑资料页
    ├── language_page.dart            # 语言选择页
    ├── blocklist_page.dart           # 黑名单页（框架）
    ├── network_diagnostics_page.dart # 网络诊断页
    ├── about_page.dart               # 关于页
    ├── theme_view.dart               # 主题选择页
    └── widgets/
        ├── settings_section_header.dart
        └── theme_option_tile.dart

data/remote/
├── get_profile_request.dart          # GET /app/api/user/profile（已有）
└── update_profile_request.dart       # POST /app/api/user/update-profile（新增）

---

3. 数据流

3.1 资料加载

SettingsPage (build)
  └─ ref.watch(settingsViewModelProvider)
       └─ SettingsViewModel.build()
            └─ Future.microtask(loadProfile)
                 └─ FetchProfileUseCase.execute()
                      └─ NetworksSdkApi.executeRequest(GetProfileRequest())
                           └─ GET /app/api/user/profile  (JWT token in header)
                           └─ ProfileResponse → SettingsState {nickname, avatarUrl, maskedContact, uid}

3.2 退出登录

SettingsPage._confirmLogout()
  └─ AlertDialog confirm
       └─ SettingsViewModel.logout()
            ├─ LogoutUseCase.execute()
            │    ├─ AuthRepository.logout()      → POST /app/api/auth/logout
            │    ├─ SocketManager.disconnect()   → 断开 WebSocket
            │    └─ StorageSdkLifecycle.closeDatabase()
            └─ AuthNotifier.logout()             → go_router 重定向 /login

3.3 编辑资料保存

EditProfilePage → 保存按钮
  └─ EditProfileViewModel.save()
       └─ UpdateProfileUseCase.execute(nickname, bio, profilePicUrl)
            └─ NetworksSdkApi.executeRequest(UpdateProfileRequest)
                 └─ POST /app/api/user/update-profile
  └─ SettingsViewModel.loadProfile()  (刷新资料卡)

---

4. API 端点

操作	Method	Path
获取当前用户资料	GET	/app/api/user/profile
更新用户资料	POST	/app/api/user/update-profile
退出登录	POST	/app/api/auth/logout
黑名单列表（待实现）	GET	/app/api/account/block/list
解除拉黑（待实现）	POST	/app/api/account/block/remove
聊天文件夹（待实现）	POST	/app/api/account/store/get-store

---

5. Provider 设计

所有 Settings ViewModel 使用 Notifier<T> + 手动 NotifierProvider，不使用 @riverpod 代码生成，避免额外 build_runner 依赖：

class SettingsViewModel extends Notifier<SettingsState> { ... }

final settingsViewModelProvider = NotifierProvider<SettingsViewModel, SettingsState>(
  SettingsViewModel.new,
);

DI 链路：

settingsViewModelProvider
  └─ fetchProfileUseCaseProvider   → networkSdkApiProvider
  └─ logoutUseCaseProvider
       ├─ authRepositoryProvider   → networkSdkApiProvider
       ├─ socketManagerProvider
       └─ storageSdkProvider

---

6. 路由

新增 Shell 外全屏路由（parentNavigatorKey: _rootKey），TabBar 在子页面隐藏：

/settings/edit-profile        EditProfilePage
/settings/blocklist           BlocklistPage
/settings/language            LanguagePage
/settings/network-diagnostics NetworkDiagnosticsPage
/settings/about               AboutPage
/settings/theme               ThemeView（原有）

认证守卫 auth_guard.dart switch 已补全上述路由。

---

7. 待完成事项

• #6 头像上传：接入 CDN upload（参考 iOS CDN 流程）
• #8 主题持久化：解开 ThemeModeNotifier.build() 和 setMode() 中的 TODO
• #10 黑名单 API：实现 FetchBlocklistUseCase + UnblockUseCase
• #11 聊天文件夹：ChatCategoryViewModel + account/store API
• build_runner：UpdateProfileRequest 使用 @ApiRequest，需执行：

  cd apps/im_app && dart run build_runner build --delete-conflicting-outputs