XuqmGroup-RNSDK/packages/update/README.md

# @xuqm/rn-update

Android 整包更新与 RN 多 Bundle 插件运行时。它依赖 `@xuqm/rn-common` 的唯一配置和会话，不提供第二套初始化、登录、网络或文件实现。

当前发布范围为 Android。iOS 插件事务实现完成并通过验证前，不作为本包的已支持能力发布。

## 最小接入

```bash
pnpm add @xuqm/rn-common @xuqm/rn-update \
  @react-native-async-storage/async-storage
pnpm exec xuqm-rn init
pnpm run xuqm:doctor
```

`xuqm-rn init` 生成 schema v3 `xuqm.config.json` 并补充最少脚本。版本只有两条明确来源：

- 完整 App 版本来自宿主 `package.json.version`，医网信新包从 `8.0.0` 开始。
- 插件默认版本来自 `xuqm.config.json.pluginVersion`，从 `1.0.0` 开始；仅独立发布的模块覆盖 `moduleVersion`。

app/buz 使用 `commonVersionRange` 声明 SemVer 兼容范围，并使用 `minNativeApiLevel` 声明最低原生能力。Bundle 只接受 SHA-256，不使用 MD5。

## 开发与打包

- `pnpm android`：安装 Debug 包、连接 Metro、支持热刷新。
- `pnpm release:android`：重新构建并内嵌全部 startup/common/app/buz 后生成 Release AAB。
- `pnpm release:android -- --apk`：生成包含同一批插件的 Release APK。
- `pnpm publish:android`：上传插件产物；SDK npm 制品发布只能通过 Jenkins。

Android 宿主只应用一次 SDK 脚本：

```groovy
apply from: file("../../node_modules/@xuqm/rn-update/android/xuqm-bundles.gradle")
```

该脚本关闭 React Native 默认单体 Bundle，避免宿主同时维护两套启动产物。

## 运行时规则

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

XuqmRuntime.configure({
  plugins: [
    {
      moduleId: 'common',
      type: 'common',
      appVersionRange: '>=8.0.0 <9.0.0',
    },
    {
      moduleId: 'app',
      type: 'app',
      appVersionRange: '>=8.0.0 <9.0.0',
      commonVersionRange: '>=1.0.0 <2.0.0',
    },
    {
      moduleId: 'prescription',
      type: 'buz',
      appVersionRange: '>=8.0.0 <9.0.0',
      commonVersionRange: '>=1.0.0 <2.0.0',
    },
  ],
  context,
  loadBundle,
})

const startup = await XuqmRuntime.start()
```

`start()` 的固定顺序是：准备未确认事务 → 检查完整 App → 没有整包更新时检查 app+common。返回 `kind: 'app'` 时由宿主显示整包更新 UI；返回 `kind: 'plugins'` 且 `requiresColdStart` 时重启后加载并确认。

进入 buz 前只检查当前入口及 common：

```ts
const plan = await UpdateSDK.checkAndInstallPlugin('prescription', {
  onProgress(moduleId, progress) {
    console.log(moduleId, progress.percent)
  },
})
```

SDK 会验证所有已安装模块在目标 common 下仍兼容，然后整组下载、校验、staging、激活、确认或回滚。Bundle 版本与事务状态只保存在原生 state；宿主不得另建 AsyncStorage 版本表，也不得逐层传递版本或路径状态。

需要先展示插件更新提示的项目，分别调用纯检查和安装 API：

```ts
const plan = await UpdateSDK.checkPluginRelease('prescription')
if (plan && (await showPluginUpdateDialog(plan))) {
  await UpdateSDK.installPluginRelease(plan)
}
```

检查不会下载或修改状态；安装前会重新比对检查时的全部本地版本，计划过期时抛出 `StaleReleaseSetError`，调用方重新检查即可。

服务端使用单次 `POST /api/v1/rn/release-set/check` 返回目标 app/buz 与 common 的依赖闭包，不能让客户端并发拼接多个独立更新结果。