# 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`: ��道管理(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 ���址
   - `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` 追踪特定操作的完整流程