feat: add workbench kafka migration support

docs/IM-App版本更新前后端对接文档.md

@@ -0,0 +1,206 @@
+# MeetingIM App 版本更新前后端对接文档
+
+## 1. 适用范围
+
+本文档用于 iOS、Android 客户端检查新版本，以及执行推荐更新和强制更新。
+
+- 版本策略为全局配置，存储在 `hotgo.im_app_releases`，不区分租户。
+- iOS 安装包由 App Store 托管，客户端通过 `store_url` 跳转。
+- Android APK 由发布人员上传到专用 OSS 发布目录，客户端通过 `package_url` 下载。
+- 客户端不直接访问数据库，也不自行拼接 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` | 客户端平台 |
+
+### 2.2 Query 参数
+
+| 参数 | 必填 | 示例 | 说明 |
+| --- | --- | --- | --- |
+| `apikey` | 是 | `AQAAAA...` | 应用 API Key |
+| `platform` | 是 | `android` | 仅支持 `ios`、`android` |
+| `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` |
+| 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 `1.0.0` 默认策略。正式验证 Android 更新前，需要先上传测试 APK，并在 Admin 填写对应 `package_url` 与 SHA-256。