rider-pro-android-app/MIGRATION_GUIDE.md

# 腾讯云 IM SDK 到 OpenIM 迁移指南

## 迁移状态

### ✅ 已完成的工作

1. **依赖项迁移**
   - 从 `build.gradle.kts` 中移除了腾讯云 IM SDK 依赖 (`libs.imsdk.plus`)
   - 从 `gradle/libs.versions.toml` 中移除了相关版本定义
   - 保留了 OpenIM SDK 依赖 (`io.openim:android-sdk`, `io.openim:core-sdk`)

2. **核心组件迁移**
   - ✅ `TrtcHelper.kt` - 完全迁移到 OpenIM API
   - ✅ `Chat.kt` 实体类 - 更新为 OpenIM 消息模型
   - ✅ `AgentChatListViewModel.kt` - 部分迁移到 OpenIM API
   - ✅ `OpenIMManager.kt` - 完整的 OpenIM 管理器
   - ✅ `OpenIMService.kt` - OpenIM 后台服务
   - ✅ `AppState.kt` - 已使用 OpenIM 进行初始化和登录

3. **兼容层创建**
   - 创建了 `TencentIMCompat.kt` 兼容层，避免编译错误
   - 所有使用腾讯云 IM 的文件都已添加兼容层导入

4. **配置清理**
   - AndroidManifest.xml 已经是干净的，无需额外清理

### 🔄 需要进一步完成的工作

#### 1. 完整的 ViewModel 迁移
以下文件仍在使用兼容层，需要完全迁移到 OpenIM：

- `ChatViewModel.kt` - 聊天功能核心
- `ChatAiViewModel.kt` - AI 聊天功能
- `GroupChatViewModel.kt` - 群聊功能
- `FriendChatListViewModel.kt` - 好友聊天列表
- `GroupChatListViewModel.kt` - 群聊列表
- `MessageListViewModel.kt` - 消息列表
- `MineAgentViewModel.kt` - 我的智能体
- `CreateGroupChatViewModel.kt` - 创建群聊

#### 2. UI 组件迁移
以下 Screen 文件需要更新以使用新的数据模型：

- `ChatScreen.kt`
- `ChatAiScreen.kt`
- `GroupChatScreen.kt`

#### 3. 消息类型映射
需要完善 OpenIM 消息类型到应用内部类型的映射：

```kotlin
// OpenIM 消息类型
101 -> TEXT
102 -> IMAGE  
103 -> AUDIO
104 -> VIDEO
105 -> FILE
```

## OpenIM 集成状态

### ✅ 已集成的功能

1. **SDK 初始化** - `OpenIMManager.initSDK()`
2. **用户登录** - `AppState.loginToOpenIM()`
3. **连接监听** - 连接状态、踢下线、token 过期
4. **消息监听** - 新消息、消息撤回、已读回执等
5. **会话管理** - 会话变化、未读数统计
6. **用户信息管理** - 用户资料更新
7. **好友关系管理** - 好友申请、添加、删除等
8. **群组管理** - 群信息变更、成员管理等

### 🔧 需要实现的功能

1. **消息发送**
   ```kotlin
   // 需要实现
   OpenIMClient.getInstance().messageManager.sendMessage(...)
   ```

2. **历史消息获取**
   ```kotlin
   // 需要实现
   OpenIMClient.getInstance().messageManager.getAdvancedHistoryMessageList(...)
   ```

3. **会话列表获取**
   ```kotlin
   // 已在 AgentChatListViewModel 中部分实现
   OpenIMClient.getInstance().conversationManager.getAllConversationList(...)
   ```

4. **图片消息处理**
   - 需要适配 OpenIM 的 `PictureElem` 结构
   - 更新图片显示逻辑

## 迁移步骤建议

### 第一阶段：核心聊天功能
1. 完成 `ChatViewModel.kt` 的完整迁移
2. 实现消息发送和接收
3. 实现历史消息加载
4. 测试基本聊天功能

### 第二阶段：会话管理
1. 完成各种 ChatListViewModel 的迁移
2. 实现会话列表的正确显示
3. 实现未读消息统计

### 第三阶段：高级功能
1. 群聊功能迁移
2. 文件、图片等多媒体消息
3. 消息状态和已读回执

### 第四阶段：清理和优化
1. 删除兼容层 `TencentIMCompat.kt`
2. 清理所有临时代码
3. 性能优化和测试

## 关键 API 对比

### 消息发送
```kotlin
// 腾讯云 IM
V2TIMManager.getMessageManager().sendMessage(message, receiver, null, ...)

// OpenIM
OpenIMClient.getInstance().messageManager.sendMessage(message, receiver, ...)
```

### 获取会话列表
```kotlin
// 腾讯云 IM
V2TIMManager.getConversationManager().getConversationList(...)

// OpenIM
OpenIMClient.getInstance().conversationManager.getAllConversationList(...)
```

### 消息监听
```kotlin
// 腾讯云 IM
V2TIMManager.getMessageManager().addAdvancedMsgListener(listener)

// OpenIM
OpenIMClient.getInstance().messageManager.setAdvancedMsgListener(listener)
```

## 注意事项

1. **数据结构差异**：OpenIM 和腾讯云 IM 的数据结构有所不同，需要仔细映射
2. **回调机制**：OpenIM 使用不同的回调接口
3. **消息 ID**：OpenIM 使用 `clientMsgID`，腾讯云使用 `msgID`
4. **时间戳**：注意时间戳的单位和格式差异
5. **用户 ID**：确保用户 ID 在两个系统中的一致性

## 测试建议

1. **单元测试**：为每个迁移的组件编写测试
2. **集成测试**：测试完整的聊天流程
3. **兼容性测试**：确保与现有数据的兼容性
4. **性能测试**：对比迁移前后的性能表现

## 删除兼容层的时机

当以下条件都满足时，可以安全删除 `TencentIMCompat.kt`：

1. 所有 ViewModel 都已完全迁移到 OpenIM
2. 所有功能都已测试通过
3. 没有编译错误
4. 应用运行正常

删除步骤：
1. 删除 `app/src/main/java/com/aiosman/ravenow/compat/TencentIMCompat.kt`
2. 从所有文件中移除 `import com.aiosman.ravenow.compat.*`
3. 清理所有相关的临时注释