196 lines
5.7 KiB
Markdown
196 lines
5.7 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
这是一个 Flutter 插件项目,为 OpenIM 即时通讯服务提供 Flutter SDK 封装。该 SDK 支持 Android、iOS 和 Windows 平台。
|
||
|
||
**核心架构:**
|
||
- Flutter 层通过 MethodChannel 与原生层通信
|
||
- Android 原生层使用 gomobile 编译的 AAR 包与 OpenIM SDK Core (Go) 交互
|
||
- iOS 原生层使用 gomobile 编译的 XCFramework 与 OpenIM SDK Core 交互
|
||
- 数据传输格式为 JSON,数据存储使用 OpenIM SDK Core 内置的 SQLite
|
||
|
||
## 常用命令
|
||
|
||
### 开发环境设置
|
||
```bash
|
||
# 安装依赖
|
||
flutter pub get
|
||
|
||
# 运行示例应用
|
||
cd example
|
||
flutter pub get
|
||
flutter run
|
||
```
|
||
|
||
### 测试
|
||
```bash
|
||
# 运行单元测试
|
||
flutter test
|
||
|
||
# 运行集成测试
|
||
cd example
|
||
flutter test integration_test/plugin_integration_test.dart
|
||
```
|
||
|
||
### 代码格式化
|
||
```bash
|
||
# 格式化代码
|
||
dart format .
|
||
|
||
# 分析代码
|
||
flutter analyze
|
||
```
|
||
|
||
### Android 构建
|
||
```bash
|
||
# 在 example 目录中构建 Android
|
||
cd example
|
||
flutter build apk
|
||
|
||
# 构建 Android AAR
|
||
cd android
|
||
./gradlew assembleRelease
|
||
```
|
||
|
||
### iOS 构建
|
||
```bash
|
||
# 在 example 目录中构建 iOS
|
||
cd example
|
||
flutter build ios
|
||
```
|
||
|
||
## 核心架构设计
|
||
|
||
### 1. 管理器层次结构
|
||
|
||
`IMManager` 是核心管理器,包含以下子管理器:
|
||
- `ConversationManager`: 会话管理(lib/src/manager/im_conversation_manager.dart)
|
||
- `MessageManager`: 消息管理(lib/src/manager/im_message_manager.dart)
|
||
- `FriendshipManager`: 好友关系管理(lib/src/manager/im_friendship_manager.dart)
|
||
- `GroupManager`: 群组管理(lib/src/manager/im_group_manager.dart)
|
||
- `ChannelManager`: <20><>道管理(lib/src/manager/im_channel_manager.dart)
|
||
- `UserManager`: 用户管理(lib/src/manager/im_user_manager.dart)
|
||
|
||
### 2. 双向通信机制
|
||
|
||
**Flutter → Native (方法调用):**
|
||
- Flutter 通过 MethodChannel 调用原生方法
|
||
- 参数统一使用 `_buildParam()` 封装,添加 `ManagerName` 和清理空值
|
||
- 每个请求可携带 `operationID` 用于追踪
|
||
|
||
**Native → Flutter (回调监听):**
|
||
- 原生层通过 MethodChannel 回调 Flutter 层
|
||
- Flutter 在 `IMManager._addNativeCallback()` 中统一处理所有监听器回调
|
||
- 监听器类型定义在 `lib/src/enum/listener_type.dart`
|
||
|
||
### 3. 数据模型转换
|
||
|
||
所有数据模型位于 `lib/src/models/`,使用 JSON 序列化/反序列化:
|
||
- `Utils.toObj()`: JSON Map 转对象
|
||
- `Utils.toList()`: JSON Array 转对象列表
|
||
- 所有模型类实现 `fromJson()` 和 `toJson()` 方法
|
||
|
||
### 4. 监听器系统
|
||
|
||
监听器定义在 `lib/src/listener/`,主要包括:
|
||
- `OnConnectListener`: 连接状态监听
|
||
- `OnAdvancedMsgListener`: 高级消息监听
|
||
- `OnConversationListener`: 会话变化监听
|
||
- `OnFriendshipListener`: 好友关系监听
|
||
- `OnGroupListener`: 群组事件监听
|
||
- `OnChannelListener`: 频道事件监听
|
||
- `OnUserListener`: 用户信息监听
|
||
|
||
### 5. 原生层实现
|
||
|
||
**Android (Java):**
|
||
- 插件入口: `android/src/main/java/io/openim/flutter_openim_sdk/FlutterOpenimSdkPlugin.java`
|
||
- 各管理器实现: `android/src/main/java/io/openim/flutter_openim_sdk/manager/`
|
||
- 依赖的 OpenIM SDK Core AAR 包位于 `android/libs/`
|
||
|
||
**iOS (Swift/ObjC):**
|
||
- 插件入口: `ios/Classes/SwiftFlutterOpenimSdkPlugin.swift`
|
||
- 模块化管理器: `ios/Classes/Module/`
|
||
- 工具类: `ios/Classes/Util/`
|
||
|
||
## 开发注意事项
|
||
|
||
### SDK 初始化和登录流程
|
||
|
||
1. **必须先初始化 SDK** (`initSDK()` 或 `init()`)
|
||
2. **设置监听器** (必须在登录前完成)
|
||
3. **登录** (`login()`)
|
||
4. SDK 初始化需要提供:
|
||
- `platformID`: 平台 ID (参考 `IMPlatform` 枚举)
|
||
- `apiAddr`: OpenIM Server API <20><><EFBFBD>址
|
||
- `wsAddr`: OpenIM Server WebSocket 地址
|
||
- `dataDir`: 数据存储目录
|
||
|
||
### 消息收发
|
||
|
||
- 创建消息使用 `MessageManager.create*Message()` 系列方法
|
||
- 发送消息使用 `MessageManager.sendMessage()`
|
||
- 接收消息通过 `OnAdvancedMsgListener` 监听
|
||
- 支持单聊、群聊、在线消息等多种场景
|
||
|
||
### 平台特定功能
|
||
|
||
- **Android 独有**: `setListenerForService()` - 用于后台服务监听
|
||
- **通知可见性规则**: Android SDK 35+ 支持的通知管理功能
|
||
- **文件上传**: 支持自定义上传监听器 (`OnUploadFileListener`)
|
||
|
||
### 版本管理
|
||
|
||
- SDK 版本定义在 `lib/src/openim.dart` 中的 `OpenIM.version`
|
||
- `pubspec.yaml` 中的版本应与之保持一致
|
||
- 使用格式: `major.minor.patch+build` (如 `3.8.3+2`)
|
||
|
||
### 日志和调试
|
||
|
||
- 使用 `Logger.print()` 输出日志 (lib/src/logger.dart)
|
||
- 支持上传日志到服务器: `uploadLogs()`
|
||
- 可自定义日志级别 (1-6,默认 6 为全部输出)
|
||
|
||
## Android 特定配置
|
||
|
||
### ProGuard 规则
|
||
|
||
项目使用 ProGuard 混淆,规则文件在 `example/android/app/proguard-rules.pro`:
|
||
```proguard
|
||
-keep class io.openim.** { *; }
|
||
-keep class open_im_sdk.** { *; }
|
||
-keep class open_im_sdk_callback.** { *; }
|
||
```
|
||
|
||
### Gradle 配置
|
||
|
||
- 使用阿里云 Maven 镜像加速依赖下载
|
||
- 本地 Maven 仓库: `http://192.168.77.132:8081/repository/mvn2-group` (需根据实际情况修改)
|
||
- `compileSdkVersion`: 34
|
||
- `minSdkVersion`: 21
|
||
|
||
## 常见任务
|
||
|
||
### 添加新的 API 方法
|
||
|
||
1. 在对应的 Manager 类(Dart)中添加方法
|
||
2. 在 Android Manager 类(Java)中实现
|
||
3. 在 iOS Module 类(Swift)中实现
|
||
4. 确保参数序列化和回调处理正确
|
||
|
||
### 添加新的监听器
|
||
|
||
1. 在 `lib/src/listener/` 创建监听器类
|
||
2. 在 `ListenerType` 枚举中添加类型
|
||
3. 在 `IMManager._addNativeCallback()` 中添加处理逻辑
|
||
4. 在原生层实现对应的回调触发
|
||
|
||
### 调试原生层交互
|
||
|
||
- Flutter → Native: 在 `Logger.print()` 查看方法调用日志
|
||
- Native → Flutter: 在 `_addNativeCallback()` 设置断点查看回调数据
|
||
- 使用 `operationID` 追踪特定操作的完整流程
|