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

# React Native 授权管理（License SDK）

**包名**：`@xuqm/rn-license` · **依赖**：`react-native-quick-crypto`（peer dep）

---

## 1. 安装

```bash
yarn add @xuqm/rn-license react-native-quick-crypto
```

iOS 需要执行 `pod install`：

```bash
cd ios && pod install
```

---

## 2. 放置 License 文件

从租户平台下载 `.xuqmlicense` 加密文件，通过 `react-native-raw-text` 或 `require()` 将其作为文本资源嵌入 App。

**方式一：require 字符串资源（推荐）**

```ts
// 将 license.xuqm 放入 src/assets/
const licenseContent = require('./assets/license.xuqm')
```

**方式二：手动初始化**

```ts
import { initialize } from '@xuqm/rn-license'

initialize('your_app_key', {
  baseUrl: 'https://auth.dev.xuqinmin.com',
})
```

---

## 3. 检查授权

```ts
import { initializeFromFile, checkLicense } from '@xuqm/rn-license'

// 启动时从加密文件自动初始化
const licenseContent = require('./assets/license.xuqm')
await initializeFromFile(licenseContent)

// 检查授权（有缓存时直接返回，否则网络验证）
const result = await checkLicense()
if (result.type === 'success') {
  console.log('授权通过:', result.reason)
} else {
  console.warn('授权失败:', result.message)
}
```

---

## 4. 携带用户信息

```ts
import type { LicenseUserInfo } from '@xuqm/rn-license'

const userInfo: LicenseUserInfo = {
  userId: 'user_001',
  name: '张三',
  email: 'zhangsan@company.com',
}

const result = await checkLicense(userInfo)
```

---

## 5. API 说明

### initialize

```ts
initialize(appKey: string, options?: { baseUrl?: string; deviceName?: string }): void
```

手动初始化，适用于不使用 License 文件的场景。

### initializeFromFile

```ts
initializeFromFile(encryptedContent: string): Promise<void>
```

从加密 License 文件内容自动解析 appKey 和 baseUrl 并初始化。

### checkLicense

```ts
checkLicense(userInfo?: LicenseUserInfo): Promise<LicenseResult>
```

返回 `{ type: 'success', reason: string }` 或 `{ type: 'error', message: string }`。

**缓存策略**：10 分钟有效期，有效期内直接返回缓存结果（不发起网络请求）。

### getStatus

```ts
getStatus(): Promise<LicenseStatus>  // 'ok' | 'denied' | 'unknown'
```

### getDeviceId

```ts
getDeviceId(): Promise<string>
```

### clear

```ts
clear(): Promise<void>
```

---

## 6. 数据存储

| 数据 | 存储方式 |
|------|---------|
| deviceId | AsyncStorage |
| token | AsyncStorage |
| 授权状态 | AsyncStorage |
| statusTime | AsyncStorage |

---

## 7. 离线模式

- 首次激活需要网络连接
- 激活后 10 分钟缓存内可离线使用
- 网络异常时，若历史缓存成功，继续返回授权通过

---

## 8. 完整示例

```ts
import React, { useEffect, useState } from 'react'
import { View, Text } from 'react-native'
import { initializeFromFile, checkLicense } from '@xuqm/rn-license'

export default function App() {
  const [licensed, setLicensed] = useState<boolean | null>(null)

  useEffect(() => {
    async function verify() {
      const content = require('./assets/license.xuqm')
      await initializeFromFile(content)
      const result = await checkLicense({ userId: 'user_001' })
      setLicensed(result.type === 'success')
    }
    verify()
  }, [])

  if (licensed === null) return <Text>验证中...</Text>
  if (!licensed) return <Text>授权验证失败，请联系管理员</Text>
  return <View>{ /* 主界面 */ }</View>
}
```

---

## 9. 常见问题

**Q: 提示 `react-native-quick-crypto not available`？**
确认已安装 `react-native-quick-crypto` 并执行了 `pod install`（iOS）或重新 build（Android）。

**Q: License 文件如何用 require 加载？**
需要在 Metro 配置中将 `.xuqm` 加入 `assetExts`：

```js
// metro.config.js
const config = {
  resolver: {
    assetExts: [...defaultConfig.resolver.assetExts, 'xuqm'],
  },
}
```