zhini_im/client SDK升级指南.md

# Client SDK 升级指南

## 📋 当前项目配置

### 1. Client 模块信息
- **模块类型**: 本地模块（Local Module）
- **模块路径**: `client/`
- **包名**: `cn.wildfirechat.client`
- **当前版本号**: `clientVersion = 200`（在 `ClientService.java` 中定义）
- **依赖关系**: 
  - 依赖 `mars-core-release` 模块
  - 依赖 AndroidX Lifecycle 组件

### 2. 相关文件位置
- **ClientService.java**: `client/src/main/java/cn/wildfirechat/client/ClientService.java`
- **build.gradle**: `client/build.gradle`
- **版本号定义**: `ClientService.java:205` - `private int clientVersion = 200;`

## 🔄 升级方式

### 方式一：从 Git 仓库更新（推荐）

如果 client 模块是从野火 IM 官方仓库拉取的代码，可以通过 Git 更新：

#### 1. 检查 Git 远程仓库
```bash
cd client
git remote -v
```

#### 2. 拉取最新代码
```bash
# 查看远程分支
git fetch origin

# 查看当前分支和远程分支的差异
git log HEAD..origin/main --oneline

# 合并最新代码（谨慎操作，建议先备份）
git pull origin main
```

#### 3. 解决冲突
如果本地有修改，可能会产生冲突：
```bash
# 查看冲突文件
git status

# 手动解决冲突后
git add .
git commit -m "Merge latest client SDK"
```

### 方式二：手动替换代码

如果 client 模块是手动集成的，需要手动替换：

#### 1. 备份当前代码
```bash
# 备份整个 client 目录
cp -r client client_backup_$(date +%Y%m%d)
```

#### 2. 下载新版本
- 从野火 IM 官方仓库下载最新版本的 `client` 模块
- 或从官方发布页面下载 SDK 包

#### 3. 替换代码
```bash
# 删除旧的 client 目录（保留备份）
rm -rf client

# 复制新版本
cp -r /path/to/new/client client
```

#### 4. 合并自定义修改
如果有自定义修改，需要手动合并：
- 对比新旧版本的差异
- 将自定义修改应用到新版本

### 方式三：使用 Maven/Gradle 依赖（如果官方提供）

如果野火 IM 官方提供了 Maven 仓库，可以在 `app/build.gradle` 中配置：

```gradle
dependencies {
    // 替换本地模块依赖为远程依赖
    // implementation project(':client')
    implementation 'cn.wildfirechat:client:最新版本号'
}
```

**注意**: 需要先确认官方是否提供 Maven 仓库。

## 📝 升级步骤

### 步骤 1: 检查当前版本
查看 `ClientService.java` 中的版本号：
```java
private int clientVersion = 200;  // 当前版本
```

### 步骤 2: 查看更新日志
- 查看野火 IM 官方更新日志
- 了解新版本的功能和修复
- 确认是否有破坏性变更

### 步骤 3: 备份项目
```bash
# 备份整个项目
git commit -a -m "Backup before client SDK upgrade"
# 或创建分支
git checkout -b backup-before-sdk-upgrade
```

### 步骤 4: 更新代码
根据选择的升级方式执行更新操作。

### 步骤 5: 更新版本号
在 `ClientService.java` 中更新版本号：
```java
private int clientVersion = 新版本号;  // 例如: 201, 202 等
```

### 步骤 6: 检查依赖兼容性
检查 `client/build.gradle` 中的依赖是否需要更新：
```gradle
dependencies {
    api project(':mars-core-release')
    api "androidx.lifecycle:lifecycle-viewmodel:2.8.7"
    api "androidx.lifecycle:lifecycle-livedata:2.8.7"
    api "androidx.lifecycle:lifecycle-process:2.8.7"
    api 'com.squareup.okhttp3:okhttp:4.12.0'
    implementation 'com.squareup.okio:okio:3.10.2'
}
```

### 步骤 7: 同步 Gradle
```bash
# 同步项目
./gradlew clean
./gradlew build
```

### 步骤 8: 测试验证
- 编译项目，确保无编译错误
- 运行应用，测试核心功能
- 检查是否有 API 变更需要适配

## ⚠️ 注意事项

### 1. 版本兼容性
- 检查新版本是否与当前 Android SDK 版本兼容
- 检查是否与 `mars-core-release` 版本兼容
- 检查是否与其他模块版本兼容

### 2. API 变更
- 查看官方更新日志中的 API 变更说明
- 检查是否有废弃的方法需要替换
- 检查是否有新增的必需配置

### 3. 配置文件
- 检查 `AndroidManifest.xml` 是否需要更新
- 检查权限配置是否需要调整
- 检查 ProGuard 规则是否需要更新

### 4. 自定义修改
如果对 client 模块有自定义修改，需要：
- 记录所有自定义修改点
- 在新版本中重新应用这些修改
- 测试自定义功能是否正常

### 5. 数据库迁移
如果新版本涉及数据库结构变更：
- 查看数据库迁移指南
- 备份用户数据
- 测试数据迁移流程

## 🔍 版本号说明

### Client 版本号
- **位置**: `ClientService.java:205`
- **格式**: 整数（如 200, 201, 202）
- **用途**: 标识客户端 SDK 版本，用于服务端兼容性检查

### 获取当前版本
```java
// 在代码中获取
ChatManager.Instance().getClientVersion();
```

## 📚 相关资源

### 官方资源
- 野火 IM 官方文档: https://docs.wildfirechat.cn/
- GitHub 仓库: https://github.com/wildfirechat/android-chat
- 更新日志: 查看官方仓库的 CHANGELOG 或 Release Notes

### 项目内参考
- `android-chat-master/`: 参考项目目录
- `client/build.gradle`: Client 模块构建配置
- `mars-core-release/`: 网络通信核心模块

## 🛠️ 常见问题

### Q1: 升级后编译失败
**解决方案**:
1. 清理项目: `./gradlew clean`
2. 检查依赖版本是否兼容
3. 查看编译错误日志，逐个解决

### Q2: 升级后功能异常
**解决方案**:
1. 查看官方更新日志，了解变更
2. 检查是否有 API 调用方式变更
3. 查看官方迁移指南

### Q3: 如何回退版本
**解决方案**:
```bash
# 如果使用 Git
git checkout <旧版本commit>

# 如果手动替换
# 从备份恢复
cp -r client_backup_YYYYMMDD client
```

## 📌 升级检查清单

- [ ] 备份当前代码
- [ ] 查看官方更新日志
- [ ] 检查版本兼容性
- [ ] 更新代码
- [ ] 更新版本号
- [ ] 同步 Gradle
- [ ] 编译测试
- [ ] 功能测试
- [ ] 性能测试
- [ ] 更新文档

---

**最后更新**: 2025年11月8日
**适用版本**: Client SDK v200+