XuqmGroup-Web/docs-site/docs/rn/index.md

# React Native SDK 概览

**包名**：`@xuqm/rn-sdk` · **版本**：0.1.0 · **支持**：React Native 0.73+、Expo 50+

## 功能模块

| 导出 | 功能 |
|------|------|
| `XuqmSDK` | 全局初始化 |
| `ImSDK` | 单聊、群聊、消息收发、历史记录 |
| `UpdateSDK` | App 版本检查、RN Bundle 热更新 |
| `PushSDK` | 设备 Token 上报 |

## 安装

### 从 Nexus 私有仓库安装

在项目根目录创建 `.npmrc`：

```
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm-hosted/
```

然后安装：

```bash
npm install @xuqm/rn-sdk
# 或
yarn add @xuqm/rn-sdk
```

## 快速接入

### 1. 初始化（一次即可，在 App 启动时调用）

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

XuqmSDK.init({
  appId:      'your_app_id',
  appKey:     'your_app_id',
  appSecret:  'your_app_secret',
  apiBaseUrl: 'https://sentry.xuqinmin.com',
  imWsUrl:    'wss://sentry.xuqinmin.com/ws/im',
  debug:      __DEV__,
})
```

### 2. IM 登录

```ts
import { ImSDK } from '@xuqm/rn-sdk'

await ImSDK.login('user_001', '张三')
```

### 3. 监听消息与连接事件

```ts
import type { ImEventListener } from '@xuqm/rn-sdk'

const listener: ImEventListener = {
  onConnected()           { console.log('WS connected') },
  onDisconnected(reason)  { console.log('WS disconnected:', reason) },
  onMessage(msg)          { /* 单聊/群聊消息 */ },
  onGroupMessage(msg)     { /* 群消息（独立回调） */ },
  onError(err)            { console.error(err) },
}

ImSDK.addListener(listener)

// 组件卸载时移除
return () => {
  ImSDK.removeListener(listener)
  ImSDK.disconnect()
}
```

### 4. 发送消息

```ts
// 文本
const sent = await ImSDK.sendMessage('user_002', 'SINGLE', 'TEXT', 'Hello!')

// 图片（content 为 JSON 字符串）
const sent = await ImSDK.sendMessage('user_002', 'SINGLE', 'IMAGE', JSON.stringify({
  url: 'https://cdn.example.com/img.jpg',
  width: 800, height: 600,
}))
```

### 5. 撤回消息

```ts
const revoked = await ImSDK.revokeMessage(msg.id)
```

### 6. 拉取历史

```ts
// 单聊历史（page=0, size=50）
const history = await ImSDK.fetchHistory('user_002', 0, 50)

// 群历史
const gHistory = await ImSDK.fetchGroupHistory(groupId, 0, 50)
```

### 7. 群聊

```ts
// 创建群（自动将自己加入成员列表）
const group = await ImSDK.createGroup('开发讨论组', ['user_001', 'user_002'])

// 订阅群 WebSocket topic
ImSDK.subscribeGroup(group.id)

// 列出所有群
const groups = await ImSDK.listGroups()

// 发群消息
const sent = await ImSDK.sendMessage(group.id, 'GROUP', 'TEXT', '大家好')
```

### 8. 检查 App 更新

```ts
import { UpdateSDK } from '@xuqm/rn-sdk'

const info = await UpdateSDK.checkAppUpdate(1 /* 当前 versionCode */)
if (info) {
  console.log(info.versionName, info.forceUpdate, info.downloadUrl)
}
```

### 9. RN Bundle 热更新（三步流程）

```ts
import AsyncStorage from '@react-native-async-storage/async-storage'

// Step 1: 检查是否有新版本
const bundle = await UpdateSDK.checkRNUpdate('home', '1.0.0')
if (!bundle) return // 已是最新

// Step 2: 下载 bundle
const content = await UpdateSDK.downloadBundle(bundle.downloadUrl)

// Step 3: 缓存，下次启动由 BundleRuntime 加载
await AsyncStorage.setItem('rn_bundle_home', JSON.stringify({
  version: bundle.version,
  md5:     bundle.md5,
  content,
  cachedAt: new Date().toISOString(),
}))
```

> **提示**：运行时替换（热加载）需对接原生 `BundleRuntime`，参考 `ProjectFrameReactNative` 架构文档。

## 完整消息类型

```ts
type MsgType =
  | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'FILE'
  | 'CUSTOM' | 'LOCATION' | 'NOTIFY' | 'RICH_TEXT'
  | 'CALL_AUDIO' | 'CALL_VIDEO' | 'FORWARD' | 'REVOKED'
```

每种类型的 `content` 格式：

| MsgType | content |
|---------|---------|
| `TEXT` | 纯文本字符串 |
| `IMAGE` | `{"url":"...","width":800,"height":600,"thumbnailUrl":"..."}` |
| `VIDEO` | `{"url":"...","duration":30,"thumbnailUrl":"...","size":1048576}` |
| `AUDIO` | `{"url":"...","duration":12,"size":204800}` |
| `FILE` | `{"url":"...","name":"report.pdf","size":512000,"mimeType":"application/pdf"}` |
| `LOCATION` | `{"lat":39.9042,"lng":116.4074,"address":"北京市东城区","title":"天安门"}` |
| `CUSTOM` | 任意 JSON 字符串 |
| `NOTIFY` | `{"title":"系统通知","content":"服务器维护","level":"INFO"}` |
| `RICH_TEXT` | `{"html":"<b>加粗</b>内容"}` |
| `CALL_AUDIO` | `{"callId":"uuid","action":"INVITE","callerName":"张三"}` |
| `CALL_VIDEO` | `{"callId":"uuid","action":"INVITE","callerName":"张三"}` |
| `FORWARD` | `{"originalMsgId":"...","originalContent":"原始内容","originalSender":"张三"}` |
| `REVOKED` | 服务端下发，客户端只读 |

## TypeScript 类型定义

```ts
interface ImMessage {
  id:         string
  appId:      string
  fromUserId: string
  toId:       string
  chatType:   'SINGLE' | 'GROUP'
  msgType:    MsgType
  content:    string
  status:     'SENT' | 'REVOKED'
  createdAt:  string   // ISO 8601
}

interface ImGroup {
  id:        string
  appId:     string
  name:      string
  creatorId: string
  memberIds: string[]
  adminIds:  string[]
  createdAt: string
}
```