# 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 或用户状态。

无法使用配置文件自动初始化时，才调用一次：

```ts
await XuqmSDK.initialize({appKey: 'app-key'});
```

## 开发与验证

要求 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`。