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

我的（Mine）Tab — 架构文档

对应 Gitea issues #5–#13，#39–#41（UI 重设计），#49–#50（编辑资料完整实现） 参考实现：im-client-ios-swift-demo Features/Settings + Features/Profile

---

1. 功能范围

Issue	功能	状态
#5	Tab 重命名 & 个人资料卡片	✅ 已实现
#6	编辑个人资料（昵称/bio/头像）	✅ 全量实现（#49/#50 补全头像上传）
#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 编辑资料 — 头像上传（#49）

EditProfilePage._showAvatarSourceSheet()
  └─ BottomSheet → 相册 / 拍照
       └─ EditProfileViewModel.pickAndUploadAvatar(ImageSource)
            ├─ ImagePicker.pickImage(source, maxWidth:900, maxHeight:900, quality:85)
            ├─ ImageCropper.cropImage(1:1, IOSUiSettings / AndroidUiSettings)
            ├─ state.isUploadingAvatar = true
            ├─ NetworksSdkApi.executeRequest(UploadFileRequest(filePath))
            │    └─ POST /app/api/upload/file （FormData multipart）
            │         └─ UploadResult.url
            └─ state.avatarUrl = url  （UI 实时预览更新）

3.4 编辑资料保存（#50）

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

---

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. UI 重设计（#39 / #40 / #41）

7.1 ProfileHeroCard (#39 / #41)

元素	规格
头像	72pt 圆形；无头像时 8 色渐变占位（uid%8）
昵称	fontWeight w700，titleMedium
Handle	@J{uid}，bodySmall onSurfaceVariant
手机号	掩码 +CC ***XXXX，bodySmall
Bio	非空显示，为空显示「添加一句话简介」（斜体，半透明）
AppBar	compact，右侧：QR 图标 + 编辑铅笔

渐变色方案（_ProfileHeroCard._gradients[uid.abs() % 8]）：

0: [#4776E6, #8E54E9]  1: [#11998E, #38EF7D]
2: [#FC466B, #3F5EFB]  3: [#F7971E, #FFD200]
4: [#56CCF2, #2F80ED]  5: [#EB3349, #F45C43]
6: [#1FA2FF, #12D8FA]  7: [#9D50BB, #6E48AA]

7.2 彩色图标行与分组卡片 (#40)

_IconBox：36pt 圆角正方形（8pt）白色图标，iOS Settings 风格。

卡片组	菜单项	颜色
账户	我的钱包	#FFAA5B
	账户安全	#8A5CF6
工具	收藏	#FFAF45
	最近呼叫	#4CB050
	链接设备	#5667FF
	聊天文件夹	#F2994A
偏好设置	通知和声音	#FF8B5E
	隐私设置	#0BB8A9
	黑名单	#FF4B4B
	语言	#5667FF
	主题	#8A5CF6
关于	用户协议	gray
	隐私政策	gray
	版本号（静态）	gray，无 chevron

7.3 SettingsState bio 字段 (#41)

• SettingsState.bio: String（默认 ''）
• SettingsViewModel.loadProfile() 赋值 bio: profile.bio
• 数据来源：ProfileResponse.bio → GET /app/api/user/profile

---

8. 编辑资料 UI 设计（#49 / #50）

元素	规格
头像	88pt 圆形；无头像时 8 色渐变占位；右下 28pt 相机角标（primary色）
上传进度	CircularProgressIndicator 环绕头像，isUploadingAvatar=true 时显示
选图 Sheet	BottomSheet（从相册选取 / 拍照），16pt 圆角，拖动条
昵称字段	Card 分组，x/50 右侧计数，maxLength:50
简介字段	Card 分组，x/200 右侧计数，maxLines:null（自动展开），maxLength:200
保存按钮	AppBar 右侧 TextButton；昵称为空或上传中时 disabled
错误 Banner	errorContainer 色圆角卡片，⚠️ 图标 + 文本

---

9. 待完成事项

• #8 主题持久化：解开 ThemeModeNotifier.build() 和 setMode() 中的 TODO
• #10 黑名单 API：实现 FetchBlocklistUseCase + UnblockUseCase
• #11 聊天文件夹：ChatCategoryViewModel + account/store API