# React Native 版本更新接入指南

**包名**：`@xuqm/rn-update` · **功能**：App 版本检查、RN Bundle 热更新、打开商店

---

## 1. 安装

```bash
yarn add @xuqm/rn-update
```

`rn-update` 会自动依赖 `@xuqm/rn-common` 和 `@xuqm/rn-sdk`。

---

## 2. App 版本检查

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

const appUpdate = await UpdateSDK.checkAppUpdate()
if (appUpdate.needsUpdate) {
  console.log('新版本:', appUpdate.versionName)
  console.log('更新日志:', appUpdate.changeLog)
  console.log('下载地址:', appUpdate.downloadUrl)

  if (appUpdate.forceUpdate) {
    // 强制更新
    showForceUpdateModal(appUpdate)
  } else {
    // 可选更新
    showOptionalUpdateModal(appUpdate)
  }
}
```

App 版本号自动从原生模块读取，无需手动传入。开发/模拟器环境可调用 `_devSetAppVersion` 覆盖：

```ts
// 仅限开发环境使用
UpdateSDK._devSetAppVersion(100, '1.0.0')
```

---

## 3. 打开商店

```ts
await UpdateSDK.openStore(appUpdate.appStoreUrl, appUpdate.marketUrl)
```

- iOS：打开 `appStoreUrl`
- Android：打开 `marketUrl`

---

## 4. RN Bundle 热更新

### 4.1 注册插件

在插件 Bundle 的入口文件顶部注册插件元数据：

```ts
// plugin/index.ts
import { UpdateSDK } from '@xuqm/rn-update'
import meta from './plugin.json'

UpdateSDK.registerPlugin(meta)
```

`plugin.json` 示例：

```json
{
  "moduleId": "home",
  "version": "1.2.3"
}
```

### 4.2 检查热更新

```ts
const rnUpdate = await UpdateSDK.checkRnUpdate('home')
if (rnUpdate.needsUpdate) {
  console.log('最新版本:', rnUpdate.latestVersion)
  console.log('下载地址:', rnUpdate.downloadUrl)
  console.log('更新说明:', rnUpdate.note)
  console.log('最低依赖版本:', rnUpdate.minCommonVersion)
}
```

### 4.3 下载并缓存 Bundle

```ts
// 下载 Bundle 源码
const source = await UpdateSDK.downloadRnBundle(rnUpdate.downloadUrl)

// 缓存到本地
await UpdateSDK.cacheRnBundle('home', rnUpdate.latestVersion, rnUpdate.md5, source)

// 读取已缓存的 Bundle
const cached = await UpdateSDK.getCachedRnBundle('home')
if (cached) {
  console.log('缓存版本:', cached.version)
  console.log('缓存时间:', cached.downloadedAt)
}
```

### 4.4 获取已注册插件版本

```ts
const version = UpdateSDK.getRegisteredPluginVersion('home')
console.log('当前运行版本:', version)
```

---

## 5. 强制更新处理

当 `appUpdate.forceUpdate` 为 `true` 时，建议业务层：

1. 弹出不可关闭的 Modal
2. 只允许用户点击「立即更新」
3. 调用 `UpdateSDK.openStore()` 跳转商店

```ts
function showForceUpdateModal(update: AppUpdateInfo) {
  // 使用 RN Modal 组件，设置不可取消
  Alert.alert(
    '发现重要更新',
    `当前版本已不可用，请升级至 ${update.versionName}`,
    [
      {
        text: '立即更新',
        onPress: () => UpdateSDK.openStore(update.appStoreUrl, update.marketUrl),
      },
    ],
    { cancelable: false }
  )
}
```

---

## 6. 多模块统一登录

Update 模块与 IM、Push 模块共享同一套登录态：

```ts
await XuqmSDK.initialize({ appKey: 'your_app_key' })
await XuqmSDK.login({ userId: 'user_001', userSig: 'your_user_sig_jwt' })
// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作
```

---

## 7. 一键打包上传

SDK 提供 `xuqm_release.mjs` 脚本，可一键完成 RN Bundle 构建并上传至 XuqmGroup 版本管理服务：

```bash
node scripts/xuqm_release.mjs --platform android --env production
```

脚本执行流程：
1. 执行 `react-native bundle` 构建 JS Bundle
2. 自动提取模块 ID、版本号、更新日志
3. 上传 Bundle 到 XuqmGroup 后台
4. 返回发布结果

常用参数：

| 参数 | 说明 |
|------|------|
| `--platform` | 平台：`android` / `ios` |
| `--env` | 环境：`production` / `staging` |
| `--moduleId` | 模块 ID（如 `home`）|
| `--forceUpdate` | 是否强制更新 |

在 `package.json` 中添加快捷命令：

```json
{
  "scripts": {
    "xuqm:release": "node scripts/xuqm_release.mjs --platform android --env production"
  }
}
```