diff --git a/README.md b/README.md new file mode 100644 index 0000000..ce9105e --- /dev/null +++ b/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 { + 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` 中配置自定义仓库地址。 diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md new file mode 100644 index 0000000..245327e --- /dev/null +++ b/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"}` diff --git a/docs/PLATFORM_OVERVIEW.md b/docs/PLATFORM_OVERVIEW.md new file mode 100644 index 0000000..6cda91b --- /dev/null +++ b/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 `，由 `POST /api/auth/login` 颁发 +- **IM 服务**：`Authorization: Bearer `，由 `POST /api/im/auth/login` 颁发；WebSocket 连接时通过 URL 参数 `?token=` 传递 +- **运营平台**：`Authorization: Bearer `，由 `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` |