# 安装与自动配置

## 环境要求

- React Native `0.76` 或更高版本
- Node.js 当前 LTS
- Android `minSdk 24` 或更高版本
- 使用原生模块时，需要标准 React Native 原生工程或完成 Prebuild 的 Expo 工程

SDK 当前以 Android 为完整验证平台。页面中明确标记为 Android 的能力不能据此推断为
iOS 已支持。

## 配置 npm 仓库

宿主从只读聚合仓库安装依赖：

```ini
# .npmrc
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/
```

请使用租户平台为当前应用推荐的精确版本。开发和测试阶段可能使用带 `alpha`、`beta`、
`rc` 或 `SNAPSHOT` 标识的预发布版本，不要自行改成无预发布标识的版本。

## 按需安装

只使用通用基础能力：

```bash
pnpm add @xuqm/rn-common axios \
  @react-native-async-storage/async-storage
```

使用版本更新：

```bash
pnpm add @xuqm/rn-common @xuqm/rn-update \
  @react-native-async-storage/async-storage
```

使用 WebView：

```bash
pnpm add @xuqm/rn-common @xuqm/rn-xwebview \
  react-native-webview react-native-safe-area-context react-native-svg
```

其他模块同样按需安装：

```bash
pnpm add @xuqm/rn-bugcollect
pnpm add @xuqm/rn-im @nozbe/watermelondb
pnpm add @xuqm/rn-push
```

项目使用 npm 或 Yarn 时，可以使用等价安装命令；不要同时维护多份锁文件。

## 获取配置文件

使用扩展包时，在租户平台进入目标应用并下载配置文件。将下载文件原名放到：

```text
src/assets/config/<平台生成的文件名>.xuqmconfig
```

约束：

- 目录中只能存在一个 `.xuqmconfig`。
- 不要重命名内容、手工编辑或提交到公共仓库。
- 公有化和私有化平台生成的配置不能混用。
- 重新生成配置后，下一次构建必须使用新文件。
- Common 独立模式不要放置配置文件。

建议加入忽略规则：

```gitignore
src/assets/config/*.xuqmconfig
```

## 配置 Metro

没有启用插件化时，只包装一次 Common：

```js
// metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const { withXuqmConfig } = require('@xuqm/rn-common/metro')

const config = mergeConfig(getDefaultConfig(__dirname), {
  // 宿主自己的 Metro 配置
})

module.exports = withXuqmConfig(config)
```

启用 RN 插件化时使用 Update 提供的组合器，不要再叠加 `withXuqmConfig`：

```js
const { getDefaultConfig } = require('@react-native/metro-config')
const { withXuqmModuleConfig } = require('@xuqm/rn-update/metro')

module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname))
```

两种配置二选一。项目只能存在一个 Metro 配置出口。

## Android 仓库

原生依赖从 XuqmGroup Android 聚合仓库读取：

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
  repositories {
    maven("https://nexus.xuqinmin.com/repository/android/")
    google()
    mavenCentral()
  }
}
```

React Native 自动链接会处理已安装模块。只有 Update 插件化宿主需要按其页面说明应用
一次 Bundle 构建脚本。

## 启动前检查

```ts
import { XuqmSDK } from '@xuqm/rn-common'

const state = XuqmSDK.getInitializationState()
// idle | initializing | ready | degraded | failed
```

一般业务无需等待初始化。确实需要在首屏执行扩展操作时：

```ts
await XuqmSDK.awaitInitialization()
```

持续失败时按错误码展示非阻断提示，不要让 SDK 服务异常替代宿主首页。

## Debug 策略

- `pnpm start` 和 `pnpm android` 使用标准 Metro 与 Fast Refresh。
- Debug 默认不自动检查整包或插件更新。
- Debug 默认不自动上传 BugCollect。
- 需要验证服务时，通过对应模块的显式测试入口触发。

## 验收清单

- 工程中只有一份 `.xuqmconfig`。
- Metro 只使用一个 Xuqm 包装器。
- Common-only 工程不要求初始化。
- App 启动时没有手写 AppKey、平台地址或内部服务地址。
- 登录只调用一次公共会话入口。
- Release 构建使用租户平台当前有效配置。