xuqinmin12/XuqmGroup-HarmonySDK
0
0
派生 0
代码 工单 合并请求 版本发布 百科 动态

docs: add detailed documentation

浏览代码
这个提交包含在：
XuqmGroup 2026-04-21 22:25:35 +08:00
父节点 90bd57a69c
当前提交 fe8b72d2be
共有 3 个文件被更改，包括 600 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

232
README.md 普通文件
查看文件

@ -0,0 +1,232 @@
# XuqmGroup HarmonyOS SDK 文档
> ArkTS · HarmonyOS 5 (API 12) · 发布至 ohpm
## 模块结构
```
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` 中配置自定义仓库地址。

279
docs/DEPLOY.md 普通文件
查看文件

@ -0,0 +1,279 @@
# 部署文档
## 一、基础设施要求
| 组件 | 版本 | 说明 |
|------|------|------|
| JDK | 21 | GraalVM 或 Eclipse Temurin |
| MySQL | 8.0+ | 4 个独立数据库 |
| Redis | 7.x | 验证码、会话标记 |
| Nginx | 1.24+ | 前端静态 + API 反代 |
| Maven | 3.9+ | 后端构建 |
| Node.js | 22+ | 前端构建 |
---
## 二、数据库初始化
服务启动时通过 `ddl-auto: update` 自动建表，只需提前创建数据库：
```sql
CREATE DATABASE xuqm_tenant CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE xuqm_im CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE xuqm_push CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE xuqm_update CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
---
## 三、后端构建与启动
### 构建
```bash
cd XuqmGroup-Server
mvn clean package -DskipTests
```
各模块 jar 生成于 `{module}/target/{module}-0.1.0-SNAPSHOT.jar`。
### 环境变量
**tenant-service**（:8081）
```bash
export SPRING_DATASOURCE_URL=jdbc:mysql://db:3306/xuqm_tenant?...
export SPRING_DATASOURCE_USERNAME=xuqm
export SPRING_DATASOURCE_PASSWORD=your_db_password
export SPRING_DATA_REDIS_HOST=redis
export SPRING_MAIL_USERNAME=noreply@xuqm.com
export SPRING_MAIL_PASSWORD=your_smtp_password
export JWT_SECRET=your_256bit_secret
export OPS_ADMIN_USERNAME=admin
export OPS_ADMIN_PASSWORD=your_ops_password
```
**im-service**（:8082）
```bash
export SPRING_DATASOURCE_URL=jdbc:mysql://db:3306/xuqm_im?...
export SPRING_DATASOURCE_USERNAME=xuqm
export SPRING_DATASOURCE_PASSWORD=your_db_password
export SPRING_DATA_REDIS_HOST=redis
export JWT_SECRET=your_256bit_secret_im
```
**push-service**（:8083）
```bash
export SPRING_DATASOURCE_URL=jdbc:mysql://db:3306/xuqm_push?...
export SPRING_DATASOURCE_USERNAME=xuqm
export SPRING_DATASOURCE_PASSWORD=your_db_password
export JWT_SECRET=your_256bit_secret_push
# 华为推送
export HUAWEI_APP_ID=your_huawei_app_id
export HUAWEI_APP_SECRET=your_huawei_secret
# 小米推送
export XIAOMI_APP_SECRET=your_xiaomi_secret
# iOS APNs
export APNS_KEY_ID=your_key_id
export APNS_TEAM_ID=your_team_id
export APNS_KEY_PATH=/opt/xuqm/apns_key.p8
export APNS_BUNDLE_ID=com.yourcompany.app
```
**update-service**（:8084）
```bash
export SPRING_DATASOURCE_URL=jdbc:mysql://db:3306/xuqm_update?...
export SPRING_DATASOURCE_USERNAME=xuqm
export SPRING_DATASOURCE_PASSWORD=your_db_password
export JWT_SECRET=your_256bit_secret_update
export UPDATE_UPLOAD_DIR=/data/xuqm/update
export UPDATE_BASE_URL=https://update.xuqm.com
```
### 启动
```bash
java -jar tenant-service/target/tenant-service-*.jar &
java -jar im-service/target/im-service-*.jar &
java -jar push-service/target/push-service-*.jar &
java -jar update-service/target/update-service-*.jar &
```
---
## 四、前端构建与部署
```bash
cd XuqmGroup-Web
yarn install
yarn workspace tenant-platform build # dist/ → /var/www/tenant
yarn workspace ops-platform build # dist/ → /var/www/ops
```
### Nginx 配置
```nginx
# 租户开放平台
server {
listen 80;
server_name tenant.xuqm.com;
root /var/www/tenant;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://127.0.0.1:8081/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
# 运营管理平台
server {
listen 80;
server_name ops.xuqm.com;
root /var/www/ops;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://127.0.0.1:8081/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
# IM WebSocket 反代
server {
listen 80;
server_name im.xuqm.com;
location /ws/im {
proxy_pass http://127.0.0.1:8082;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
}
location /api/im/ {
proxy_pass http://127.0.0.1:8082/api/im/;
}
}
# 版本管理文件服务
server {
listen 80;
server_name update.xuqm.com;
location / {
proxy_pass http://127.0.0.1:8084/;
}
}
```
---
## 五、Docker Compose（可选）
```yaml
version: '3.9'
services:
mysql:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_USER: xuqm
MYSQL_PASSWORD: xuqm_password
volumes:
- mysql_data:/var/lib/mysql
ports:
- "3306:3306"
redis:
image: redis:7-alpine
ports:
- "6379:6379"
tenant-service:
image: eclipse-temurin:21-jre
volumes:
- ./XuqmGroup-Server/tenant-service/target:/app
command: java -jar /app/tenant-service-0.1.0-SNAPSHOT.jar
environment:
SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/xuqm_tenant?...
SPRING_DATA_REDIS_HOST: redis
ports:
- "8081:8081"
depends_on: [mysql, redis]
im-service:
image: eclipse-temurin:21-jre
volumes:
- ./XuqmGroup-Server/im-service/target:/app
command: java -jar /app/im-service-0.1.0-SNAPSHOT.jar
ports:
- "8082:8082"
depends_on: [mysql, redis]
push-service:
image: eclipse-temurin:21-jre
volumes:
- ./XuqmGroup-Server/push-service/target:/app
command: java -jar /app/push-service-0.1.0-SNAPSHOT.jar
ports:
- "8083:8083"
depends_on: [mysql]
update-service:
image: eclipse-temurin:21-jre
volumes:
- ./XuqmGroup-Server/update-service/target:/app
- update_files:/data/xuqm/update
command: java -jar /app/update-service-0.1.0-SNAPSHOT.jar
environment:
UPDATE_UPLOAD_DIR: /data/xuqm/update
ports:
- "8084:8084"
depends_on: [mysql]
volumes:
mysql_data:
update_files:
```
---
## 六、发版流程汇总
| 平台 | 步骤 |
|------|------|
| **后端** | `mvn clean package` → 替换 jar → 重启服务 |
| **前端** | `yarn build` → 替换 `dist/` → Nginx 无需重启 |
| **Android SDK** | 修改版本号 → `./gradlew publish` → Nexus |
| **iOS SDK (SPM)** | 修改版本号 → `git tag x.y.z && git push origin x.y.z` |
| **iOS SDK (CocoaPods)** | `pod repo push xuqm-specs XuqmSDK.podspec` |
| **RN SDK** | 修改 `package.json` version → `npm publish` |
| **Vue3 SDK** | 修改 `package.json` version → `npm run build && npm publish` |
| **HarmonyOS SDK** | 修改 `oh-package.json5` version → `ohpm publish` |
---
## 七、健康检查
各服务均暴露 Spring Actuator 端点：
```bash
curl http://localhost:8081/actuator/health
curl http://localhost:8082/actuator/health
curl http://localhost:8083/actuator/health
curl http://localhost:8084/actuator/health
```
正常返回：`{"status":"UP"}`

89
docs/PLATFORM_OVERVIEW.md 普通文件
查看文件

@ -0,0 +1,89 @@
# XuqmGroup 平台文档总览
> 版本：0.1.0 | 最后更新：2026-04-21
## 仓库索引
| 仓库 | 语言/框架 | Gogs 地址 | 说明 |
|------|-----------|-----------|------|
| [XuqmGroup-Server](./server/README.md) | Java 21 / Spring Boot 3.4 | https://xuqinmin.com/xuqinmin12/XuqmGroup-Server | 后端多模块服务 |
| [XuqmGroup-Web](./web/README.md) | Vue 3.5 / TypeScript | https://xuqinmin.com/xuqinmin12/XuqmGroup-Web | 租户平台 + 运营平台前端 |
| [XuqmGroup-AndroidSDK](./android-sdk/README.md) | Kotlin 2.3 / AGP 9.1 | https://xuqinmin.com/xuqinmin12/XuqmGroup-AndroidSDK | Android SDK |
| [XuqmGroup-iOSSDK](./ios-sdk/README.md) | Swift 5.9 / iOS 16+ | https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK | iOS SDK |
| [XuqmGroup-RNSDK](./rn-sdk/README.md) | TypeScript / RN 0.76+ | https://xuqinmin.com/xuqinmin12/XuqmGroup-RNSDK | React Native SDK |
| [XuqmGroup-Vue3SDK](./vue3-sdk/README.md) | TypeScript / Vue 3.5 | https://xuqinmin.com/xuqinmin12/XuqmGroup-Vue3SDK | Vue3 Web SDK |
| [XuqmGroup-HarmonySDK](./harmony-sdk/README.md) | ArkTS / HarmonyOS 5 | https://xuqinmin.com/xuqinmin12/XuqmGroup-HarmonySDK | 鸿蒙 SDK |
## 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ Android SDK iOS SDK RN SDK Vue3 SDK HarmonyOS SDK │
└───────────────────────────┬─────────────────────────────────┘
│ HTTPS / WSS
┌───────────────────────────▼─────────────────────────────────┐
│ 服务端层 │
│ ┌────────────┐ ┌──────────┐ ┌───────────┐ ┌────────────┐ │
│ │tenant-svc │ │im-service│ │push-svc │ │update-svc │ │
│ │ :8081 │ │ :8082 │ │ :8083 │ │ :8084 │ │
│ └─────┬──────┘ └────┬─────┘ └─────┬─────┘ └──────┬─────┘ │
│ └─────────────┴─────────────┴───────────────┘ │
│ ↓ JPA / JDBC │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ MySQL 8 (xuqm_tenant / xuqm_im / xuqm_push / │ │
│ │ xuqm_update) + Redis 7 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 前端层 │
│ 租户开放平台 :5173 运营管理平台 :5174 │
└─────────────────────────────────────────────────────────────┘
```
## 核心概念
| 概念 | 说明 |
|------|------|
| **租户 (Tenant)** | 在开放平台注册的主账号，可创建子账号 |
| **应用 (App)** | 租户创建的业务应用，具有唯一 appKey/appSecret |
| **功能服务 (FeatureService)** | 挂载在 App 下的服务实例（IM / 推送 / 版本管理），按平台（Android / iOS / HarmonyOS）独立开启 |
| **IM 账号** | 业务方通过 appKey 在 IM 服务创建的用户，仅存 userId，不存昵称/头像 |
| **运营平台** | 内部管理后台，独立账号体系，不与租户共用 |
## 统一响应格式
所有 HTTP 接口均返回：
```json
{
"code": 200,
"status": "0",
"data": { ... },
"message": "success"
}
```
| 字段 | 含义 |
|------|------|
| `code` | HTTP 语义码，200 成功，4xx/5xx 失败 |
| `status` | `"0"` 成功，`"1"` 业务失败 |
| `data` | 业务数据，失败时为 null |
| `message` | 错误描述 |
## 认证方式
- **租户平台**：`Authorization: Bearer <tenant_jwt>`，由 `POST /api/auth/login` 颁发
- **IM 服务**：`Authorization: Bearer <im_jwt>`，由 `POST /api/im/auth/login` 颁发；WebSocket 连接时通过 URL 参数 `?token=<im_jwt>` 传递
- **运营平台**：`Authorization: Bearer <ops_jwt>`，由 `POST /api/auth/ops/login` 颁发
## 发版信息
| 平台 | Registry | 命令 |
|------|----------|------|
| npm (RN SDK / Vue3 SDK) | https://nexus.xuqinmin.com/repository/npm-hosted/ | `npm publish` |
| Android Maven | https://nexus.xuqinmin.com/repository/android-hosted/ | `./gradlew publish` |
| iOS SPM | Git Tag | `git tag x.y.z && git push origin x.y.z` |
| iOS CocoaPods | https://xuqinmin.com/xuqinmin12/xuqm-specs | `pod repo push xuqm-specs XuqmSDK.podspec` |
| HarmonyOS | ohpm (OpenHarmony Package Manager) | `ohpm publish` |