XuqmGroup-Server/docs/PLATFORM_OVERVIEW.md

# 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` |
| npm download | https://nexus.xuqinmin.com/repository/npm/ | client consumption |
| Android Maven upload | https://nexus.xuqinmin.com/repository/android-hosted/ | `./gradlew publish` |
| Android Maven download | https://nexus.xuqinmin.com/repository/android/ | client consumption |
| Java Maven upload (release) | https://nexus.xuqinmin.com/repository/maven-releases/ | `mvn deploy` |
| Java Maven upload (snapshot) | https://nexus.xuqinmin.com/repository/maven-snapshots/ | `mvn deploy` |
| Java Maven download | https://nexus.xuqinmin.com/repository/maven-public/ | client consumption |
| 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` |