XuqmGroup-iOSSDK/README.md

# XuqmGroup iOS SDK 文档

> Swift 5.9 · iOS 16+ · macOS 13+ · async/await

## 模块结构

```
XuqmGroup-iOSSDK/
├── Package.swift              # SPM 包定义
├── XuqmSDK.podspec            # CocoaPods 发版描述
├── XuqmWebViewSDK.podspec     # WebView 独立模块发版描述
├── PUBLISH.md                 # 发版操作手册
├── Sources/XuqmCoreSDK/       # 核心：初始化、HTTP、Token
├── Sources/XuqmImSDK/         # IM：WebSocket 实时通信
├── Sources/XuqmPushSDK/       # 推送：APNs Token 注册
├── Sources/XuqmUpdateSDK/     # 版本管理：检查更新
├── Sources/XuqmLicenseSDK/    # 授权管理
├── Sources/XuqmFileSDK/       # 文件上传、下载、本地打开
└── Sources/XuqmWebViewSDK/    # WebView 嵌入式组件 / 独立页面
    ├── XWebViewBridge.swift   # 页面配置 / 控制器桥接
    ├── XWebViewPage.swift     # 独立页面
    ├── XWebViewTypes.swift    # 配置 / 控制器协议
    └── XWebViewView.swift     # 嵌入式组件
```

## 集成

### Swift Package Manager（推荐）

在 Xcode → File → Add Package Dependencies，输入仓库地址：
```
https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK.git
```
选择版本规则 `Up to Next Major: 0.1.0`。

或在 `Package.swift` 中添加：
```swift
dependencies: [
    .package(url: "https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK.git", from: "0.1.0")
],
targets: [
    .target(name: "YourApp", dependencies: ["XuqmSDK", "XuqmWebViewSDK"])
]
```

### CocoaPods

```ruby
# Podfile
source 'https://xuqinmin.com/xuqinmin12/xuqm-specs.git'
source 'https://cdn.cocoapods.org/'

pod 'XuqmSDK', '~> 0.1.0'
pod 'XuqmWebViewSDK', '~> 0.1.0'
```

---

## 快速开始

### 1. 初始化（AppDelegate / @main）

```swift
import XuqmSDK

@main
struct MyApp: App {
    init() {
        XuqmSDK.initialize(
            appKey: "ak_your_app_key",
            appSecret: "as_your_app_secret",
            debug: true
        )
    }
}
```

### 2. 登录后存储 Token

```swift
// 调用你的业务登录接口获得 token
await XuqmSDK.setToken(token)
```

### 3. WebView 独立模块

`XuqmWebViewSDK` 不需要单独初始化，直接依赖即可使用。

```swift
import XuqmWebViewSDK

// 嵌入式组件：直接放到任意 SwiftUI 页面中
XWebViewView(
    config: XWebViewConfig(
        url: "https://example.com",
        title: "嵌入式网页"
    )
)

// 独立页面：在导航栈中直接 push
NavigationLink("打开页面模式") {
    XWebViewPage(
        config: XWebViewConfig(
            url: "https://example.com",
            title: "独立页面"
        )
    )
}
```

---

## Core

### ApiClient

基于 `URLSession`，async/await，自动附加 Bearer Token，统一解析 `ApiResponse<T>`。

```swift
// 定义响应模型
struct LoginResponse: Decodable {
    let token: String
}

// 发起请求
let response: LoginResponse = try await ApiClient.post(
    path: "/api/im/auth/login",
    body: ["appKey": appKey, "userId": userId]
)
```

### TokenStore

基于 `Keychain` 存储（`kSecClassGenericPassword`），App 重启后自动恢复。

```swift
await XuqmSDK.setToken("eyJ...")    // 存储
let token = XuqmSDK.getToken()      // 读取（同步）
await XuqmSDK.setToken(nil)         // 清除（登出）
```

---

## IM

### ImClient

```swift
import XuqmSDK

class ChatViewController: UIViewController, ImEventDelegate {

    let imClient = ImClient()

    override func viewDidLoad() {
        super.viewDidLoad()
        imClient.delegate = self
        imClient.connect()
    }

    // 发送消息
    func sendMessage() throws {
        try imClient.send(SendMessageParams(
            toId: "user_002",
            chatType: .single,
            msgType: .text,
            content: "Hello!"
        ))
    }

    // 撤回消息
    func revokeMessage(msgId: String) throws {
        try imClient.revoke(msgId: msgId)
    }

    deinit { imClient.disconnect() }
}

// MARK: - ImEventDelegate
extension ChatViewController {
    func onConnected() { print("IM 连接成功") }
    func onDisconnected(code: Int, reason: String) { print("断开: \(code)") }
    func onMessage(_ msg: ImMessage) { /* 更新 UI */ }
    func onRevoke(msgId: String, operatorId: String) { /* 标记消息已撤回 */ }
    func onError(_ error: Error) { print("错误: \(error)") }
}
```

### ImMessage 结构

```swift
public struct ImMessage: Decodable {
    public let id: String
    public let fromId: String
    public let toId: String
    public let chatType: ChatType      // single / group
    public let msgType: MsgType
    public let content: String
    public let extra: String?
    public let revoked: Bool
    public let createdAt: String
    public let editedAt: Int64?
}
```

### 消息类型（MsgType）

`text` / `image` / `video` / `audio` / `file` / `custom` / `location` / `notify` / `richText` / `callAudio` / `callVideo` / `forward`

### 自动重连

断线后指数退避重连，初始 3s，最大 30s。`disconnect()` 后停止。

---

## Push

```swift
import XuqmSDK

// 在 didRegisterForRemoteNotificationsWithDeviceToken 中调用
func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Task {
        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
        try await PushSDK.registerToken(
            token,
            userId: "user_001"
        )
    }
}
```

`PushSDK.registerToken` 内部将 `Data` 转换为十六进制字符串，vendor 固定为 `APNS`。

---

## Update

### 检查原生版本更新

```swift
import XuqmSDK

let result = try await UpdateSDK.checkAppUpdate(currentVersionCode: 123)
if result.needsUpdate, let info = result.info {
    print("最新版本: \(info.versionName)")
    // iOS 只能跳转 App Store
    if let url = URL(string: info.appStoreUrl) {
        await UIApplication.shared.open(url)
    }
}
```

`UpdateSDK` 这里只负责 iOS App 版本更新。RN 热更新如果需要，走独立的 RN SDK / RN 更新模块，不并入统一发版能力。

`XuqmWebViewSDK` 提供独立的 WebView 组件和页面，可与 `XuqmSDK` 同时使用，也可单独依赖。

---

## XuqmFileSDK

文件上传、下载、本地打开的统一入口。`XuqmImSDK` 和 `XuqmWebViewSDK` 均依赖此模块。

### 上传

```swift
import XuqmFileSDK

let result: FileUploadResult = try await FileSDK.shared.upload(
    fileURL: localFileURL,
    thumbnailData: thumbnailJpegData  // 可选
)
// result.url / .thumbnailUrl / .hash / .size / .mimeType / .ext
```

### 下载

```swift
// 下载存储目标
public enum FileDownloadDestination: Sendable {
    case sandbox   // App Documents 目录（在 Files App 中以 App 名称显示）
    case userPick  // 弹出系统存储面板，由用户选择保存位置
}

// URL 下载，实时进度回调
let localURL: URL = try await FileSDK.shared.download(
    url: "https://example.com/report.pdf",
    fileName: "report.pdf",          // 可选，默认从 URL 推断
    destination: .sandbox,
    onProgress: { progress in        // 0–100
        print("下载进度：\(progress)%")
    }
)

// Blob / base64 数据写盘
let localURL: URL = try FileSDK.shared.saveBlobDownload(
    base64Data: b64String,
    fileName: "export.xlsx",
    destination: .userPick
)
```

---

## XuqmWebViewSDK

### XWebViewConfig 完整参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `url` | String | `""` | 初始加载地址 |
| `title` | String | `""` | 页面标题（独立页面模式使用） |
| `hideToolbar` | Bool | `false` | 隐藏独立页面顶栏 |
| `hideStatusBar` | Bool | `false` | 隐藏状态栏 |
| `userAgent` | String? | `nil` | 自定义 User-Agent |
| `injectedJavaScript` | String? | `nil` | 页面加载后注入的额外 JS |
| `downloadDestination` | FileDownloadDestination | `.sandbox` | 下载文件存储目标 |
| `onMessage` | `(String) -> Void`? | `nil` | H5 发送消息的回调 |

### 文件选择与拍照

WKWebView 原生支持 `<input type="file">`，SDK 额外处理：

- `<input type="file" capture>` 摄像头：iOS 15+ 通过 `requestMediaCapturePermissionFor` 自动授权
- 麦克风 / 摄像头 WebRTC `getUserMedia()`：自动授权

### 下载拦截与存储

```swift
XWebViewView(
    config: XWebViewConfig(
        url: "https://example.com",
        downloadDestination: .userPick  // 弹出系统 Files 存储面板
    )
)
```

- `.sandbox`：下载完成后弹出 `UIActivityViewController`（分享 / 存储到 Files）
- `.userPick`：下载完成后弹出 `UIDocumentPickerViewController`（直接选择存储位置）

### H5 监听下载进度

```javascript
// 下载进度（0–100）
window.addEventListener('__xwvDownloadProgress', (e) => {
    console.log(e.detail.url, e.detail.progress)
})

// 下载完成
window.addEventListener('__xwvDownloadDone', (e) => {
    if (e.detail.success) {
        console.log('下载成功', e.detail.url)
    } else {
        console.error('下载失败', e.detail.error)
    }
})
```

### H5 ↔ Native 消息通信

```javascript
// H5 → Native（触发 onMessage 回调）
window.webkit.messageHandlers.ReactNativeWebView.postMessage(
    JSON.stringify({ type: 'login', token: '...' })
)
```

```swift
// Native → H5
XWebViewBridge.shared.currentController()?.postMessageToWeb(
    "window.dispatchEvent(new CustomEvent('nativeMsg', { detail: { key: 'value' } }))"
)
```

---

## 发版

### SPM（推荐）

```bash
git add -A && git commit -m "release: 0.1.0"
git tag 0.1.0
git push origin main 0.1.0
```

Xcode 用户在 Package Dependencies 刷新即可获取新版本。

### CocoaPods 私有 Spec

```bash
# 首次（只需一次）
pod repo add xuqm-specs https://xuqinmin.com/xuqinmin12/xuqm-specs.git

# 每次发版
pod spec lint XuqmSDK.podspec --allow-warnings
pod repo push xuqm-specs XuqmSDK.podspec --allow-warnings
```