# XuqmGroup-RNSDK — Claude 项目上下文

## 项目定位

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

- Git 远端：`ssh://git@xuqinmin.com:2222/`（以 `git remote -v` 实际结果为准）
- Nexus npm 发布：`https://nexus.xuqinmin.com/repository/npm-hosted/`

## 包结构

| 包名 | 目录 | 当前版本 | 状态 |
|------|------|----------|------|
| `@xuqm/rn-common` | packages/common | 0.4.0 | 活跃开发 |
| `@xuqm/rn-update` | packages/update | — | 活跃开发 |
| `@xuqm/rn-xwebview` | packages/xwebview | — | 活跃开发 |
| `@xuqm/rn-log` | packages/log | 0.1.0（新） | 新建中 |
| `@xuqm/rn-push` | packages/push | — | 代码冻结（仅文档） |
| `@xuqm/rn-im` | packages/im | — | 代码冻结（仅文档） |
| `@xuqm/rn-license` | packages/license | — | 代码冻结（仅文档） |

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

## 技术约束

- **React Native ≥ 0.76**（Bridgeless Mode，New Architecture）
- **TypeScript 5.x strict** — `noImplicitAny: true`，禁止 `any`
- **向下兼容**：公开接口不删除不修改，新字段一律可选
- **无静默降级**：autoInit 失败时 `__DEV__` 模式 throw，生产模式 console.error

## 核心 API（@xuqm/rn-common）

### 初始化（两种方式，均不得修改签名）

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

**方式 B — 手动初始化**
```ts
// 仅传 appKey → 使用内置公有平台
await XuqmSDK.initialize({ appKey: 'xxx' })

// 传 appKey + platformUrl → 使用指定私有化平台
await XuqmSDK.initialize({ appKey: 'xxx', platformUrl: 'https://xxx' })

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

**两种平台互相独立，不允许自动降级到默认公有平台。**

### 用户信息
```ts
XuqmSDK.setUserInfo({ userId: 'u001', userSig: 'sig', name: '张三' })
XuqmSDK.setUserInfo(null)  // 登出
```

### 日志（@xuqm/rn-log）
```ts
import { XLog } from '@xuqm/rn-log'  // 注意是 XLog 不是 Log

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

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

## XWebView JSBridge 标准 Handler

见 `docs/XWebView-JSBridge.md`（已有文档，以该文档为准）。

## 任务文档

开发前阅读 `/Users/xuqinmin/Projects/XuqmProjects/YiwangxinApp4/docs/agent-tasks/` 中对应的 agent 任务文件：

- Agent 2 任务：`agent2-rn-common.md`
- Agent 3 任务：`agent3-rn-update-xwebview.md`
- Agent 4 任务：`agent4-rn-log.md`
- Agent 8 任务：`agent8-docs.md`

## 常用命令

```bash
yarn workspace @xuqm/rn-common typecheck
yarn workspace @xuqm/rn-log typecheck
yarn workspace @xuqm/rn-update typecheck
```