V-IM Flutter 项目介绍

# V-IM Flutter 项目介绍

## 项目定位
V-IM Flutter 是一套跨平台即时通讯客户端，目标是还原并强化 Web 端/Uni-App 版本的核心体验。应用围绕“统一消息 + 协同插件”理念构建，在同一套 Flutter 界面中提供聊天、联系人、工作台插件、个人中心等全功能入口，并兼顾移动端与桌面端的响应式布局与暗黑模式适配。

## 应用结构概览
- `lib/core`：配置、常量、依赖注入、网络封装、插件管理、主题扩展、存储与工具方法等底层能力。
- `lib/data`：按职责拆分的 API 数据源、模型与仓库，负责和后端服务通信（依赖 `dio`、`web_socket_channel` 等）。
- `lib/presentation`：页⾯、Provider 状态管理和常用组件，覆盖聊天、联系人、收藏、主导航、认证等界面。
- `lib/plugins`：按照插件划分的独立模块（云盘、视频会议、接龙、视频通话、邮件等），通过 `PluginDiscoveryService` 自动注册并挂载到工作台与消息体系。
- `test/`：与业务层级对应的单元/小部件测试目录，为持续迭代准备了结构化测试基线。

## 核心功能模块

### 启动与认证
- `SplashPage` 提供启动动效并异步检测登录态，统一跳转至主页面或登录页。
- 登录页（`presentation/pages/auth/login_page.dart`）支持验证码校验、错误提示与账号本地记忆，失败后自动刷新验证码。
- `ServerConfigPage` 允许用户在客户端直接切换服务端地址，搭配 `AppConfig` 的 `dart-define` 支持，可适配多环境部署需求。
- `AuthProvider` 负责登录状态、用户资料、Token 等信息维护，并与 `StorageService` 联动持久化。

### 实时消息与会话管理
- `WebSocketService` 管理长连接，会自动心跳、批量 ACK、断线重连，并支持好友/群组请求、消息撤回、已读回执等事件分发。
- `ChatProvider` 维护聊天列表、消息缓存、未读统计与已读状态，提供引用、撤回、消息同步等完整业务接口。
- `ChatPage` / `MessageContent` 支持文本、图片、文件、语音、视频、转发等多种消息类型；长按菜单可执行转发、引用、收藏、多选、撤回、复制/下载等操作；引用消息、高亮@、消息收藏均与 Provider 解耦实现。
- `ChatHistoryPage` 通过分页与筛选实现历史消息搜索，支持按消息类型过滤、关键词搜索、时间轴定位。
- `MessageProvider` 提供多选模式与引用状态管理，方便后续二次操作。
- `CollectPage` 形成独立的收藏夹，配合多类型 Tab 与编辑对话框管理收藏分类。
- `NotificationService` 与 `BackgroundSyncService` 共同保证后台消息同步：前者在应用进入后台时展示原生通知，后者借助 `workmanager` 定时拉取未读消息并触发提醒。

### 联系人与组织协作
- `FriendProvider`、`GroupProvider` 与多个联系人页面复刻了原有通讯录能力：好友索引按拼音分组、待审批列表、好友申请操作、群聊详情与群成员管理。
- `DeptListPage` 借助 `animated_tree_view` 构建支持懒加载与折叠的部门树；`DeptUsersPage` 结合头像组件快速浏览组织成员。
- 联系人详情、群设置、快速建群等页面均按需接入聊天跳转、免打扰、成员操作等能力，使组织协作与即时沟通无缝衔接。

### 插件工作台与生态能力
工作台（`WorkbenchPage`）通过 `PluginManager` 动态读取插件，实现模块化扩展与未读角标聚合。现有插件能力包括：

1. **云盘（`plugins/cloud_disk`）**  
   - 首页区分个人云盘与团队云盘，展示容量占用与入口（`CloudDiskHomePage`）。  
   - 浏览器页面支持面包屑导航、列表/网格切换、关键词搜索、文件类型过滤、排序、批量选择、批量删除。  
   - 提供上传文件/图片视频、创建文件夹、重命名、移动、下载、打开外链等操作，文件元数据使用 `CloudDiskRepository` 统一管理。  
   - `CloudDiskMessageUtils` 让云盘资源以插件消息形态回写聊天记录，实现“文件-消息”互通。

2. **视频会议（`plugins/meeting`）**  
   - 在聊天工具栏中暴露“视频会议”按钮（`MeetingCreatePlugin`），自动注入当前会话成员为默认参会人。  
   - `CreateMeetingPage` 支持会议名称、时间、时长、参会人多选，复用好友/群成员数据。  
   - `MeetingRoomPage` 基于 `flutter_webrtc` 与 LiveKit 服务实现多人音视频会议，提供画中画布局、全屏切换、麦克风/摄像头开关、扬声器切换与离会确认等交互。

3. **即时视频通话（`plugins/video_call`）**  
   - `VideoCallProvider` 结合 `WebSocketProvider` 管理呼叫信令，支持主动呼出与来电接听。  
   - `VideoCallPage` 同时处理纯音频与视频模式，内置画中画、主画面切换、静音/免提、挂断等控制，并通过 `VideoCallStateManager` 监听全局状态实现通话生命周期管理。

4. **接龙（`plugins/solitaire`）**  
   - `CreateSolitairePage` 面向群聊快速发起接龙：支持模板行、拖拽排序、折叠展开、成员输入限制等。  
   - `SolitaireProvider` 负责接龙消息格式化与推送，结合 `SolitaireMessageExtend` 与自定义 MessageType 在聊天内展示结果。

5. **企业邮箱 VMail（`plugins/vmail`）**  
   - `VMailIndexPage` 将收件箱、发件箱、草稿箱以卡片列表形式呈现，动态更新未读角标。  
   - `MailListPage` 与 `MailDetailPage` 负责邮件列表与正文阅读，`ComposeMailPage` 支持富文本输入、附件处理、草稿保存等，辅以 `VMailStateManager` 管理拉取和刷新。

插件体系统一走 `PluginDiscoveryService.initializeAllPlugins()` 自动注册，既能扩展工作台入口，也能向聊天消息插槽注入自定义渲染与操作。

### 个人中心与系统设置
- `MinePage` 以可滚动头图展示用户信息，并提供个人资料、修改密码、主题设置、收藏夹、聊天设置等入口。
- `ThemeProvider` 搭配 `AppTheme.lightTheme/darkTheme` 和 `AppThemeExtensions`，确保组件、提醒、弹窗在明暗模式下样式统一。`ThemeDemoPage` 方便验证主题效果。
- `SettingsPage` 汇总通知、免打扰、消息行为等偏好设置，并与 `ImmunityProvider`、`SettingProvider` 同步存储。
- 退出登录将清理 WebSocket、消息缓存与 Token，保证账号切换安全。

## 技术亮点
- **模块化插件架构**：通过 `IPluginRegistrar`、`PluginManager` 实现插件发现、依赖排序与统一初始化；消息渲染也开放给插件接管，增强可插拔性。
- **状态与依赖注入**：全局使用 Provider 管理状态，`DependencyInjection` 封装 `get_it` 注册核心服务，确保模块解耦。
- **网络层弹性**：HTTP 请求基于 `dio`，长连接使用 `web_socket_channel` 与自研重连机制；`AppConfig` 支持运行时与编译期配置覆写，方便多环境部署。
- **后台任务与通知**：`BackgroundSyncService` 结合 `workmanager` 后台拉取未读消息，`FlutterLocalNotificationsPlugin` 提供跨平台通知与点击跳转处理。
- **自动更新**：`AppUpdateService` 解析内置 `update.yaml` 与远端配置，自动下载并触发 Android 安装包更新。
- **本地存储**：`StorageService` 封装 `shared_preferences`，提供 JSON、列表等常用读写 API，并带重试保证初始化成功。
- **日志调试**：`log_utils.dart` 抽象统一日志通道，配合海量问题定位文档（`docs/` 目录）记录修复思路与排查过程。

## UI 与体验特性
- 全局使用 `flutter_screenutil` 和自定义排版体系（`AppTypographyScheme`）适配不同分辨率；暗黑模式下自动调整前景、阴影与卡片颜色。
- `AppNotifier` 统一处理轻量级提示、错误反馈与操作回调，与 `SnackBar`/Dialog 风格保持一致。
- 文件、图片、音视频等组件充分考虑 Web/桌面兼容：例如图片预览使用 `Hero` 动效，语音播放兼容 Web CORS，视频界面提供本地占位与控制面板。
- 大量页面按需懒加载，配合 `PagedListView`、`RefreshIndicator`、`FutureBuilder` 等组合保证性能与交互流畅。

## 快速上手
- **环境准备**：确保 Flutter SDK ≥ 3.8.1，并按目标平台完成 Android/iOS/Web/桌面端依赖配置。
- **安装依赖**：执行 `flutter pub get` 拉取全部包。
- **代码规范**：通过 `flutter analyze` 检查静态问题，结合 `dart format .` 与 `dart fix --apply` 保持代码整洁。
- **运行调试**：使用 `flutter run` 搭配 `-d chrome`/`windows`/`macos`/`linux`/具体设备 ID 进行启动调试。
- **测试执行**：位于 `test/` 的单元与小部件测试可通过 `flutter test` 运行，集成场景建议按需补充在 `test/integration`。

## 配置与安全
- `AppConfig` 允许使用 `--dart-define` 覆写服务端地址、协议、端口等配置，并与 `ServerConfigPage` 形成编译期 + 运行时的双重灵活性。
- `StorageService` 对用户 Token、服务器地址等敏感信息进行本地持久化，采用重试机制保证初始化成功。
- 所有网络请求默认使用 HTTPS/WSS，`WebSocketSSLConfig` 负责证书适配，避免出现明文通信风险。
- 项目严格避免硬编码密钥，外部 API、推送凭证等需通过环境变量或后端配置注入，同时资源文件统一从 `assets/` 管理。

## 亮点一览
- **全链路即时通讯体验**：从登录、实时聊天、历史搜索到收藏、通知、后台同步，完整覆盖 IM 使用链路。
- **插件生态能力强**：云盘、会议、接龙、视频通话、企业邮箱等模块通过统一接口热插拔，轻松扩展业务。
- **多端一致性**：适配暗黑模式、响应式布局和桌面交互细节，确保 Web/桌面/移动端体验统一。
- **工程化体系完善**：依赖注入、日志、自动更新、后台任务、测试基线等基础设施完备，支撑长期迭代。

## 平台与构建支持
- 仓库内预置 `android/`、`ios/`、`web/`、`windows/`、`macos/`、`linux/` 多平台工程，能够开箱即用地构建对应产物。
- 依赖清单（`pubspec.yaml`）涵盖权限处理、存储、音视频、邮箱、插件通信等跨平台常用插件，方便在 CI 或本地一键安装。
- 默认提供 `flutter analyze`、`flutter test`、`dart format` 等质量控制建议，搭配 `test/` 与 `docs/` 目录形成完善的工程化闭环。

## 结语
凭借分层清晰的架构、可扩展的插件体系与完善的即时通讯能力，V-IM Flutter 为企业级沟通工具提供了坚实基础。开发者既可以快速接入现有消息、协同、办公能力，也可以通过插件接口与 Provider 状态体系继续扩展新的业务场景。