XuqmGroup-RNSDK/CLAUDE.md

# XuqmGroup-RNSDK — Claude 项目上下文

## 项目定位

XuqmGroup React Native SDK monorepo。为集成宿主 App（如 YiwangxinApp4）提供核心能力：初始化、HTTP、设备信息、XWebView、OTA 更新、推送、IM、证书、日志追踪。

- Git 远端：`https://xuqinmin.com/xuqmGroup/XuqmGroup-RNSDK.git`
- Nexus npm 发布：`https://nexus.xuqinmin.com/repository/npm-hosted/`
- 规范文档：`XuqmGroup-Docs/design/06-sdk-cross-platform-spec.md`

## 包结构

| 包名 | 目录 | 版本 | 说明 |
|------|------|------|------|
| `@xuqm/rn-common` | packages/common | 0.4.0 | 核心层：初始化、HTTP、设备、XWebView Bridge、API hooks |
| `@xuqm/rn-update` | packages/update | 0.4.0 | OTA 热更新、APK 更新 |
| `@xuqm/rn-push` | packages/push | 0.2.2 | 厂商推送（代码冻结，仅文档） |
| `@xuqm/rn-im` | packages/im | 0.2.2 | IM 会话、消息（代码冻结，仅文档） |
| `@xuqm/rn-xwebview` | packages/xwebview | 0.2.2 | WebView 容器 + JSBridge UI 组件 |
| `@xuqm/rn-license` | packages/license | 0.3.0 | 证书授权（代码冻结，仅文档） |
| `@xuqm/rn-log` | packages/log | 0.1.0 | 日志、错误追踪、漏斗分析（新） |

**代码冻结模块（push/im/license）：不修改代码，仅补充文档。**

## 技术栈

- React Native >= 0.76（Bridgeless Mode，New Architecture）
- TypeScript 5.x strict — `noImplicitAny: true`，禁止 `any`
- yarn workspaces monorepo
- 发布到 Nexus npm 私有仓库

## 初始化（两种方式）

**方式 A — 配置文件自动初始化（推荐）**  
宿主配置 Babel alias `@xuqm/autoinit-config` → 加密配置文件（XUQM-CONFIG-V1 格式）。SDK 自动读取并初始化，App 无需调用任何 init。

**方式 B — 手动初始化**
```ts
import { XuqmSDK } from '@xuqm/rn-common'

// 公有平台
await XuqmSDK.initialize({ appKey: 'xxx' })

// 私有化平台
await XuqmSDK.initialize({ appKey: 'xxx', platformUrl: 'https://xxx' })

// 等待异步平台配置拉取
await XuqmSDK.awaitInitialization()
```

**两种平台互相独立，不允许自动降级。**

## 用户信息

```ts
XuqmSDK.setUserInfo({ userId: 'u001', userSig: 'sig', name: '张三' })
XuqmSDK.setUserInfo(null)  // 登出，触发所有子 SDK 登出
```

子 SDK 自动订阅 `setUserInfo` 事件：Push 自动注册/解绑 token，IM 自动登录/断开，Update 更新 userId。

## 日志 SDK（@xuqm/rn-log）

```ts
import { XLog } from '@xuqm/rn-log'

XLog.setLogLevel('debug')
XLog.setEnvironment('production')
XLog.startCapture()                   // 开启全局错误捕获
XLog.event('page_view', { page: 'home' })
XLog.captureError(new Error('xxx'))
XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done'])
```

`logApiUrl` 由 SDK 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。

## 关键约束

- `XuqmSDK.initialize()` 签名不得更改
- `XuqmSDK.setUserInfo()` 现有字段不得删除
- 新增字段一律为可选，有合理默认值
- 不允许静默降级（autoInit 失败时 `__DEV__` 模式 throw）
- rn-common 与 rn-log 解耦：rn-common 可独立使用；rn-log peerDep rn-common

## XWebView JSBridge 标准 Handler

见 `docs/XWebView-JSBridge.md`。

## 常用命令

```bash
yarn workspace @xuqm/rn-common typecheck
yarn workspace @xuqm/rn-log typecheck
yarn workspace @xuqm/rn-update typecheck
yarn workspace @xuqm/rn-push typecheck
yarn workspace @xuqm/rn-im typecheck
yarn workspace @xuqm/rn-xwebview typecheck
yarn workspace @xuqm/rn-license typecheck
```