XuqmGroup-iOSSDK/README.md

# XuqmGroup iOS SDK 文档

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

## 模块结构

```
XuqmGroup-iOSSDK/
├── Package.swift            # SPM 包定义
├── XuqmSDK.podspec          # CocoaPods 发版描述
├── PUBLISH.md               # 发版操作手册
└── Sources/XuqmSDK/
    ├── Core/
    │   ├── XuqmSDK.swift    # 入口：init / setToken
    │   ├── SDKConfig.swift  # 配置结构体
    │   ├── ApiClient.swift  # HTTP 客户端（URLSession）
    │   └── TokenStore.swift # Keychain Token 存储
    ├── IM/
    │   └── ImClient.swift   # WebSocket IM 客户端
    ├── Push/
    │   └── PushSDK.swift    # APNs Token 注册
    └── Update/
        └── UpdateSDK.swift  # 版本检查 / App 更新
```

## 集成

### 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"])
]
```

### CocoaPods

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

pod 'XuqmSDK', '~> 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",
            apiBaseUrl: "https://api.xuqm.com",
            imBaseUrl: "wss://im.xuqm.com",
            debug: true
        )
    }
}
```

### 2. 登录后存储 Token

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

---

## 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: ["appId": appId, "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 {
        try await PushSDK.registerToken(
            appId: "ak_xxx",
            userId: "user_001",
            token: deviceToken
        )
    }
}
```

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

---

## Update

### 检查原生版本更新

```swift
import XuqmSDK

let result = try await UpdateSDK.checkAppUpdate(appId: "ak_xxx")
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 更新模块，不并入统一发版能力。

---

## 发版

### 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
```