XuqmGroup-RNSDK/packages/update/README.md

# @xuqm/rn-update

XuqmGroup RN SDK 更新模块。提供 App 整包更新检查和 RN 插件热更新能力。

## 安装

```bash
yarn add @xuqm/rn-update @react-native-async-storage/async-storage
```

Peer dependencies：`react-native >= 0.76`，`@react-native-async-storage/async-storage >= 1.21.0`

## 快速开始

```ts
import { UpdateSDK } from '@xuqm/rn-update'

// 注册插件
UpdateSDK.registerPlugins([
  { moduleId: 'szyx' },
  { moduleId: 'miniapp' },
])

// 注入宿主 BundleRuntime
UpdateSDK.setBundleCallbacks({
  writeBundle: writeBundleFile,
  reloadBundle: loadBundle,
})

// 检查 App 更新
const info = await UpdateSDK.checkAppUpdate()
if (info.needsUpdate) {
  await UpdateSDK.downloadAndInstallApk(info.downloadUrl)
}

// 检查插件更新
const pluginInfo = await UpdateSDK.checkPluginUpdate('szyx')
if (pluginInfo.needsUpdate) {
  await UpdateSDK.updatePlugin('szyx', { onProgress: setProgress })
}
```

## API

### 插件注册

| API | 说明 |
|-----|------|
| `UpdateSDK.registerPlugins(plugins)` | 批量注册插件 |
| `UpdateSDK.registerPlugin(meta)` | 单个注册（向后兼容） |
| `UpdateSDK.setBundleCallbacks(callbacks)` | 注入宿主写入/重载能力 |
| `UpdateSDK.getRegisteredPlugins()` | 获取已注册插件列表 |

### App 整包更新

| API | 说明 |
|-----|------|
| `UpdateSDK.checkAppUpdate(bypassIgnore?)` | 检查 App 更新（30 分钟缓存） |
| `UpdateSDK.downloadApk(info, options?)` | 下载 APK，返回 ArrayBuffer（支持进度回调） |
| `UpdateSDK.downloadAndInstallApk(url, options?)` | 下载 APK 并调起系统安装器（Android） |
| `UpdateSDK.openStore(appStoreUrl?, marketUrl?)` | 跳转应用商店 |
| `UpdateSDK.getAppVersionCode()` | 获取当前 versionCode |
| `UpdateSDK.getAppVersionName()` | 获取当前 versionName |

### 插件热更新

| API | 说明 |
|-----|------|
| `UpdateSDK.checkPluginUpdate(moduleId)` | 检查插件更新（30 分钟缓存） |
| `UpdateSDK.downloadPlugin(moduleId, info, options?)` | 下载插件 bundle，返回 JS 源码（支持进度回调） |
| `UpdateSDK.updatePlugin(moduleId, options?)` | 一步完成：检查 → 下载 → 写文件 → 重载 |

### 类型定义

```ts
interface PluginRegistration {
  moduleId: string
}

interface AppUpdateInfo {
  needsUpdate: boolean
  versionName?: string
  versionCode?: number
  downloadUrl?: string
  changeLog?: string
  forceUpdate?: boolean
  appStoreUrl?: string
  marketUrl?: string
  apkHash?: string | null
}

interface PluginUpdateInfo {
  needsUpdate: boolean
  latestVersion: string
  currentVersion: string
  downloadUrl: string
  md5: string
  minCommonVersion: string
  note: string
  forceUpdate?: boolean
}

interface CachedRnBundle {
  moduleId: string
  version: string
  md5: string
  downloadedAt: string
  source: string
}

type UpdateDownloadProgress = {
  bytesDownloaded: number
  totalBytes: number
  /** 0-100 */
  percent: number
}
```

### 下载进度回调

`downloadApk()` 和 `downloadPlugin()` 支持 `onProgress` 回调，使用 `fetch + ReadableStream` 实现流式进度计算：

```ts
// 下载 APK 带进度
const buffer = await UpdateSDK.downloadApk(info, {
  onProgress: ({ bytesDownloaded, totalBytes, percent }) => {
    console.log(`下载进度: ${percent}% (${bytesDownloaded}/${totalBytes})`)
  },
})

// 下载插件 bundle 带进度
const source = await UpdateSDK.downloadPlugin('szyx', pluginInfo, {
  onProgress: ({ percent }) => setProgress(percent),
})
```

## 工作原理

- 版本号由 SDK 自动从本地 AsyncStorage 缓存读取，首次为 `0.0.0`
- 更新检查结果缓存 30 分钟（TTL），避免频繁请求
- `updatePlugin()` 内部自动完成：`checkPluginUpdate` → `fetch(downloadUrl)` → AsyncStorage 缓存 → `writeBundle` → `reloadBundle`
- `silent: true` 时跳过 `reloadBundle`，下次启动生效