XuqmGroup-HarmonySDK/README.md

# XuqmGroup HarmonyOS SDK 文档

> ArkTS · HarmonyOS 5 (API 12) · 发布至 ohpm
> 当前工程已可成功执行 `hvigorw assembleHap`

## 模块结构

```
XuqmGroup-HarmonySDK/
├── build-profile.json5          # 工程构建配置
├── hvigorfile.ts                # Hvigor 构建入口
├── oh-package.json5             # Workspace 包描述
├── xuqm-sdk/                    # SDK HAR 模块（可发布）
│   ├── Index.ets                # 统一导出入口
│   ├── oh-package.json5         # SDK 包信息（@xuqm/harmony-sdk）
│   └── src/main/ets/
│       ├── XuqmSDK.ets          # 入口类
│       ├── core/
│       │   ├── Types.ets        # 全部类型定义
│       │   ├── SDKContext.ets   # 配置 & Preferences Token 存储
│       │   └── HttpClient.ets   # HTTP 客户端（@ohos.net.http）
│       ├── im/
│       │   └── ImClient.ets     # WebSocket IM 客户端
│       ├── push/
│       │   └── PushSDK.ets      # 推送 Token 注册
│       └── update/
│           └── UpdateSDK.ets    # 版本检查 / Bundle 下载
└── entry/                       # 示例 HAP（演示用）
    └── src/main/ets/
        ├── entryability/EntryAbility.ets
        └── pages/Index.ets
```

## 环境要求

- DevEco Studio 5.0+
- HarmonyOS SDK API 12 (5.0.0.12)
- 设备/模拟器 HarmonyOS 5+

## 权限声明

在 `module.json5` 中声明：
```json5
"requestPermissions": [
  { "name": "ohos.permission.INTERNET" },
  { "name": "ohos.permission.GET_BUNDLE_INFO" }
]
```

---

## 快速开始

### 1. 添加依赖

```json5
// oh-package.json5
{
  "dependencies": {
    "@xuqm/harmony-sdk": "0.1.0"
  }
}
```

```bash
ohpm install
```

### 2. 初始化（EntryAbility.onCreate）

```typescript
import { XuqmSDK } from '@xuqm/harmony-sdk'

export default class EntryAbility extends UIAbility {
  async onCreate(): Promise<void> {
    await XuqmSDK.init(this.context, {
      appKey: 'ak_your_app_key',
      appSecret: 'as_your_app_secret',
      apiBaseUrl: 'https://api.xuqm.com',
      imBaseUrl: 'wss://im.xuqm.com',
      debug: true,
    })
  }
}
```

### 3. 设置 Token

```typescript
// 登录后
await XuqmSDK.setToken('eyJ...')

// 登出
await XuqmSDK.setToken(null)
```

Token 通过 `@ohos.data.preferences` 持久化，App 重启后自动恢复。

---

## IM 模块

### 连接与收发消息

```typescript
import { XuqmSDK, ImEventDelegate, ImMessage } from '@xuqm/harmony-sdk'

// 实现事件委托
class MyChatDelegate implements ImEventDelegate {
  onConnected(): void {
    console.log('IM 已连接')
  }
  onDisconnected(code: number, reason: string): void {
    console.log(`断开 ${code}: ${reason}`)
  }
  onMessage(msg: ImMessage): void {
    console.log('收到消息', msg.content)
  }
  onRevoke(data: { msgId: string; operatorId: string }): void {
    console.log('消息撤回', data.msgId)
  }
  onError(message: string): void {
    console.error('IM 错误', message)
  }
}

// 在页面 aboutToAppear 中
const im = XuqmSDK.im
im.delegate = new MyChatDelegate()
im.connect()

// 发送消息
im.send({
  toId: 'user_002',
  chatType: 'SINGLE',
  msgType: 'TEXT',
  content: 'Hello from Harmony!',
})

// 撤回消息
im.revoke('msg-uuid')

// 页面销毁时
im.disconnect()
```

### 消息类型（MsgType）

`TEXT` / `IMAGE` / `VIDEO` / `AUDIO` / `FILE` / `CUSTOM` / `LOCATION` / `NOTIFY` / `RICH_TEXT` / `CALL_AUDIO` / `CALL_VIDEO` / `FORWARD`

### ImMessage 结构

```typescript
interface ImMessage {
  id: string
  fromId: string
  toId: string
  chatType: 'SINGLE' | 'GROUP'
  msgType: MsgType
  content: string
  extra?: string
  revoked: boolean
  createdAt: string
}
```

### 自动重连

断线后指数退避重连：3s → 6s → 12s → 最大 30s。`disconnect()` 后停止重连。

---

## 推送模块

```typescript
import { XuqmSDK } from '@xuqm/harmony-sdk'

// 在 HarmonyOS Push 服务返回 Token 后调用
// vendor 固定为 'HARMONY'
await XuqmSDK.push.registerToken('harmony_push_token', 'user_001')

// 登出时注销
await XuqmSDK.push.unregisterToken('harmony_push_token')
```

---

## 版本管理模块

### 检查 App 更新

```typescript
import { XuqmSDK } from '@xuqm/harmony-sdk'

const result = await XuqmSDK.update.checkAppUpdate('ak_xxx')

if (result.hasUpdate && result.info) {
  const { latestVersionName, downloadUrl, forceUpdate } = result.info
  console.log(`发现新版本 ${latestVersionName}`)
  // platform 'harmony': 通常引导用户跳转应用市场
}
```

`checkAppUpdate` 内部通过 `bundleManager.getBundleInfoForSelfSync` 获取当前 `versionCode`。

### 检查 RN Bundle 热更新

```typescript
const rnResult = await XuqmSDK.update.checkRnUpdate('ak_xxx', 'main', 100)

if (rnResult.hasUpdate && rnResult.info) {
  const filePath = await XuqmSDK.update.downloadRnBundle(
    context,
    rnResult.info.downloadUrl,
    'main.harmony.bundle'
  )
  // 文件下载至 context.cacheDir/main.harmony.bundle
  // 通知 RN 引擎重新加载
}
```

---

## 发版（ohpm）

```bash
# 确认 xuqm-sdk/oh-package.json5 中 version 字段正确
cd xuqm-sdk
ohpm publish
```

发布至 `https://ohpm.openharmony.cn/ohpm/`（OpenHarmony 官方仓库）。  
私有部署可在 `publishConfig.registry` 中配置自定义仓库地址。