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-bugcollect	packages/bugcollect	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 — 手动初始化

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

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

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

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

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

用户信息

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

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

日志 SDK（@xuqm/rn-bugcollect）

import { BugCollect } from '@xuqm/rn-bugcollect'

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

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

关键约束

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

XWebView JSBridge 标准 Handler

见 docs/XWebView-JSBridge.md。

常用命令

yarn workspace @xuqm/rn-common typecheck
yarn workspace @xuqm/rn-bugcollect 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