XuqmGroup-RNSDK/README.md

# XuqmGroup React Native SDK

XuqmGroup 通用 React Native SDK 工作区。`@xuqm/rn-common` 是唯一基础包；其余扩展包都复用 common 的配置、初始化、会话、网络和通用能力。仅使用 common 时不放配置文件、不包装 Metro，也不要求初始化或登录；使用任一官方扩展时，由 `withXuqmConfig()` 在业务入口前自动启动一次共享上下文。

## 包结构

| 包                    | 用途                                                   | 可独立使用             |
| --------------------- | ------------------------------------------------------ | ---------------------- |
| `@xuqm/rn-common`     | 可选 SDK 上下文、网络、文件、时间、加密、设备与通用 UI | 是，且无需初始化或登录 |
| `@xuqm/rn-update`     | App 更新、RN 插件注册、下载、校验与运行                | 否，依赖 common        |
| `@xuqm/rn-xwebview`   | WebView、JSBridge、权限与下载                          | 否，依赖 common        |
| `@xuqm/rn-bugcollect` | 错误、事件、漏斗和批量上报                             | 否，依赖 common        |
| `@xuqm/rn-im`         | IM 连接、消息和本地数据                                | 否，依赖 common        |
| `@xuqm/rn-push`       | 多厂商原生推送桥接                                     | 否，依赖 common        |

根包 `@xuqm/rn-sdk` 只用于仓库内聚合开发，不对外发布。应用应按需安装具体包，避免引入未使用的原生能力。

## 安装

项目 `.npmrc`：

```ini
registry=https://registry.npmjs.org/
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/
```

最小安装：

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

按需增加扩展包，例如：

```bash
pnpm add @xuqm/rn-update @xuqm/rn-xwebview @xuqm/rn-bugcollect
```

## common 独立使用

只安装 common 时，可以直接调用文件、时间、网络、加密、设备和 UI 能力，不要求配置、初始化或登录。`apiRequest` 使用绝对 URL，或先调用 `configureHttp` 配置基础地址即可。

## 扩展包一次初始化、一次登录

把平台生成的 `config.xuqmconfig` 放在 `src/assets/config/`，然后只包装一次 Metro 配置。使用 update 插件化时采用 update 组合器（它已包含 common 自动初始化）：

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

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

不使用 update 时仍调用 `@xuqm/rn-common/metro` 的 `withXuqmConfig()`。两种组合器都会把初始化模块注册为 Metro pre-main module，避免 `inlineRequires` 延迟扩展包加载。应用登录成功后只更新一次公共会话：

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

await XuqmSDK.awaitInitialization()
await XuqmSDK.login({
  userId: 'user-id',
  accessToken: 'http-access-token',
  userSig: 'optional-im-credential',
})

await XuqmSDK.logout()
```

扩展包通过 `@xuqm/rn-common/internal` 接收同一次会话变化。宿主业务代码不得导入该内部子路径，也不得逐级传递公共 token 或用户状态。

平台签发配置与 Metro 自动初始化是扩展 SDK 的唯一初始化入口；不提供手动
`initialize`。common-only 宿主不放配置，也不初始化。

## 开发与验证

要求 Node.js 22、Corepack 和 pnpm 11：

```bash
corepack pnpm install
corepack pnpm validate
```

`validate` 会执行全部包的 TypeScript 校验和测试。开发 alpha 及正式包都只能由 Jenkins 发布到 Nexus，开发机不执行 npm publish。

集成 update 的宿主由 `xuqm-rn start` 和 `xuqm-rn run android` 统一代理 Metro 与 Android Debug 启动；宿主只保留简短的 `start/android` package script。

每个扩展包的安装要求与 API 以对应 `packages/<name>/README.md` 为准。整体设计见 `docs/架构总览.md`，公共接口见 `docs/SDK-API参考.md`。