# MeetingIM App 版本更新前后端对接文档

## 1. 适用范围

本文档用于 iOS、Android、Web 客户端检查新版本，以及执行推荐更新和强制更新。

- 版本策略为全局配置，存储在 `hotgo.im_app_releases`，不区分租户。
- iOS 安装包由 App Store 托管，客户端通过 `store_url` 跳转。
- Android APK 由发布人员上传到专用 OSS 发布目录，客户端通过 `package_url` 下载。
- Web 端没有安装包时，`store_url` 和 `package_url` 可以为空，使用 `update_type`、`min_supported_version` 和 `release_notes` 控制强刷、兼容提醒或维护提示。
- 客户端不直接访问数据库，也不自行拼接 OSS 地址。

## 2. 检查版本接口

```http
GET https://api.118im.com/v1/im/app/releases/latest
```

该接口允许未登录调用。

### 2.1 请求 Header

| Header | 必填 | 示例 | 说明 |
| --- | --- | --- | --- |
| `X-IM-Schema` | 是 | `1` | MeetingIM HTTP 协议版本 |
| `X-Client-Platform` | 建议 | `ios` / `android` / `web` | 客户端平台 |

### 2.2 Query 参数

| 参数 | 必填 | 示例 | 说明 |
| --- | --- | --- | --- |
| `apikey` | 是 | `AQAAAA...` | 应用 API Key |
| `platform` | 是 | `android` | 仅支持 `ios`、`android`、`web` |
| `current_version` | 是 | `1.2.0` | 当前版本，使用数字点分格式 |
| `channel` | 否 | `stable` | 发布渠道，默认 `stable` |

Android 请求示例：

```bash
curl -H 'X-IM-Schema: 1' \
  -H 'X-Client-Platform: android' \
  'https://api.118im.com/v1/im/app/releases/latest?apikey=AQAAAA...&platform=android&current_version=1.2.0&channel=stable'
```

## 3. 成功响应

```json
{
  "code": 0,
  "data": {
    "platform": "android",
    "channel": "stable",
    "current_version": "1.2.0",
    "latest_version": "1.3.0",
    "min_supported_version": "1.1.0",
    "has_update": true,
    "force_update": false,
    "update_type": "recommended",
    "release_notes": "优化消息稳定性并修复已知问题。",
    "store_url": "",
    "package_url": "https://download.example.com/app-releases/android/stable/1.3.0/meetingim-1.3.0.apk",
    "checksum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "remind_after_seconds": 86400,
    "published_at": "2026-09-12T08:00:00Z"
  },
  "request_id": "req_xxx",
  "server_time": "2026-09-12T08:10:00Z"
}
```

### 3.1 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `current_version` | string | 客户端传入的当前版本 |
| `latest_version` | string | 后台发布的最新版本 |
| `min_supported_version` | string | 最低可继续使用的版本 |
| `has_update` | boolean | 是否存在更高版本 |
| `force_update` | boolean | 是否必须完成更新后才能继续使用 |
| `update_type` | string | `none`、`recommended`、`force` |
| `release_notes` | string | 更新说明 |
| `store_url` | string | iOS App Store 地址 |
| `package_url` | string | Android APK 的 OSS/CDN HTTPS 下载地址 |
| `checksum` | string | Android APK 的 SHA-256，小写十六进制 |
| `remind_after_seconds` | number | 推荐更新关闭后再次提醒的间隔 |
| `published_at` | string | 发布时间，UTC RFC 3339 |

## 4. 更新判断规则

客户端以服务端返回结果为准，不自行重新计算强制更新规则。

| 条件 | 客户端行为 |
| --- | --- |
| `has_update=false` | 不弹更新窗口；手动检查时提示已是最新版本 |
| `has_update=true, force_update=false, update_type=recommended` | 弹推荐更新窗口，允许取消或稍后更新 |
| `has_update=true, force_update=true` | 弹强制更新窗口，不允许关闭，不允许进入主业务 |
| `update_type=none` | 不主动弹窗，可展示版本信息 |

当 `current_version < min_supported_version` 时，服务端无条件返回强制更新：

```json
{
  "has_update": true,
  "force_update": true,
  "update_type": "force"
}
```

## 5. Android APK 与 OSS

### 5.1 OSS 对象路径

建议使用独立于聊天附件的发布目录：

```text
app-releases/android/{channel}/{version}/meetingim-{version}.apk
```

示例：

```text
app-releases/android/stable/1.3.0/meetingim-1.3.0.apk
```

### 5.2 下载地址要求

1. `package_url` 必须使用 HTTPS。
2. 地址必须长期稳定，至少覆盖该版本的完整支持周期。
3. 可以使用 OSS 公共读地址，或绑定 OSS/CDN 的固定下载域名。
4. 不得把有效期只有几分钟的 OSS 签名 URL 保存到版本表。
5. 如果 Bucket 必须私有，应提供固定公开下载接口，由接口实时生成签名并返回 302；版本表保存该固定接口地址。
6. APK 响应建议设置 `Content-Type: application/vnd.android.package-archive`。
7. 文件名、对象路径和 URL 必须包含版本号，禁止覆盖旧版本对象。

聊天附件接口 `/v0/file/s/{file_id}` 需要用户鉴权，不作为 Android 安装包的默认下载地址。

### 5.3 发布步骤

1. Android 构建正式签名 APK。
2. 计算 APK 的 SHA-256。
3. 上传到 OSS 的 `app-releases/android/{channel}/{version}/` 目录。
4. 使用浏览器或 `curl -I` 验证 HTTPS 地址可以下载。
5. 在 Admin 的“IM 全局版本更新”中编辑 Android 策略。
6. 填写最新版本、最低支持版本、更新类型、更新说明、`package_url` 和 SHA-256。
7. 保存后由 Kafka `app.release.updated` 事件通知 IM Server 清理缓存。
8. 使用旧版本号请求检查接口，确认下载地址、校验值和强更状态。

计算 SHA-256 示例：

```bash
shasum -a 256 meetingim-1.3.0.apk
```

## 6. Android 客户端处理

1. 调用版本检查接口。
2. `has_update=false` 时结束检查。
3. 根据 `force_update` 展示推荐更新或不可关闭的强更弹窗。
4. 使用系统下载组件请求 `package_url`，支持进度展示和失败重试。
5. 下载完成后计算本地文件 SHA-256，并与 `checksum` 比较。
6. 校验 APK 包名和签名证书必须与已安装应用一致。
7. 通过 Android `FileProvider` 发起安装，不使用 `file://` URI。
8. 未授予“安装未知应用”权限时，引导用户进入系统授权页。
9. 强更下载或安装失败时保留重试、网络设置和退出应用入口，不能绕过进入主业务。

客户端不得在 SHA-256 或应用签名校验失败后继续安装。

## 7. iOS 客户端处理

1. iOS 只读取 `store_url`，忽略 `package_url` 和 `checksum`。
2. `store_url` 必须是 `https://apps.apple.com/...` 地址。
3. 推荐更新允许取消；强制更新不得进入主业务。
4. 点击更新后使用系统能力打开 App Store。

## 8. 错误响应

缺少或错误的 `current_version`：

```json
{
  "code": 30000,
  "reason": "MALFORMED_REQUEST",
  "message": "malformed request",
  "details": {
    "field": "current_version"
  }
}
```

| HTTP 状态 | 原因 |
| --- | --- |
| 400 | 缺少 `X-IM-Schema: 1` |
| 400 | 缺少或错误的 `current_version` |
| 400 | `platform` 不是 `ios`、`android` 或 `web` |
| 500 | Admin 版本配置缺失、格式错误或内部配置接口不可用 |

## 9. 当前测试环境

```text
Base URL: https://api.118im.com
版本接口: /v1/im/app/releases/latest
API Key: AQAAAAABAAAoeOI7tA3HsYvdzDhYhZJy
协议版本: X-IM-Schema: 1
默认渠道: stable
```

当前测试库已配置 iOS、Android、Web `1.0.0` 默认策略。正式验证 Android 更新前，需要先上传测试 APK，并在 Admin 填写对应 `package_url` 与 SHA-256。