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

docs: add detailed documentation

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

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

@ -0,0 +1,243 @@
# XuqmGroup Android SDK 文档
> Kotlin 2.3.10 · AGP 9.1.0 · minSdk 24 · compileSdk 36
## 模块结构
```
XuqmGroup-AndroidSDK/
├── sdk-core/ # 核心：初始化、HTTP、Token 存储
├── sdk-im/ # IM：WebSocket 实时通信
├── sdk-push/ # 推送：设备 Token 注册
├── sdk-update/ # 版本管理：检查更新、下载安装、RN 热更新
└── sample-app/ # 示例 App（Jetpack Compose）
```
## 集成
### Gradle（Maven 私有仓库）
在项目根 `settings.gradle.kts` 添加仓库：
```kotlin
dependencyResolutionManagement {
repositories {
maven {
url = uri("https://nexus.xuqinmin.com/repository/android-hosted/")
credentials {
username = providers.gradleProperty("NEXUS_USER").orNull ?: ""
password = providers.gradleProperty("NEXUS_PASSWORD").orNull ?: ""
}
}
}
}
```
在 `gradle.properties` 或环境变量中配置：
```properties
NEXUS_USER=your_username
NEXUS_PASSWORD=your_password
```
引入依赖：
```kotlin
dependencies {
implementation("com.xuqm:sdk-core:0.1.0")
implementation("com.xuqm:sdk-im:0.1.0") // 可选
implementation("com.xuqm:sdk-push:0.1.0") // 可选
implementation("com.xuqm:sdk-update:0.1.0") // 可选
}
```
## 快速开始
### 1. 初始化（Application.onCreate）
```kotlin
XuqmSDK.init(
context = this,
appKey = "ak_your_app_key",
appSecret = "as_your_app_secret",
apiBaseUrl = "https://api.xuqm.com",
imBaseUrl = "wss://im.xuqm.com",
debug = BuildConfig.DEBUG
)
```
### 2. 用户登录后设置 Token
```kotlin
// 调用你的业务登录接口获得 token 后
XuqmSDK.tokenStore.save(token)
```
---
## sdk-core
### SDKConfig
| 参数 | 类型 | 说明 |
|------|------|------|
| `appKey` | String | 应用 Key（租户平台获取） |
| `appSecret` | String | 应用 Secret |
| `apiBaseUrl` | String | 后端 API 地址 |
| `imBaseUrl` | String | IM WebSocket 地址（wss://） |
| `debug` | Boolean | 开启日志 |
### TokenStore
基于 `DataStore<Preferences>` 持久化存储。
```kotlin
// 存储
XuqmSDK.tokenStore.save("eyJ...")
// 读取（协程）
val token = XuqmSDK.tokenStore.get()
// 清除（登出）
XuqmSDK.tokenStore.clear()
```
### ApiClient
基于 OkHttp 5 + Retrofit 3，自动附加 Bearer Token，统一解析 `ApiResponse<T>`。
```kotlin
// 通过 RetrofitFactory 获取接口实例
val service = RetrofitFactory.create(MyApiService::class.java)
```
---
## sdk-im
### ImClient
```kotlin
val imClient = ImClient()
// 注册事件监听
imClient.listener = object : ImEventListener {
override fun onConnected() { /* WebSocket 连接成功 */ }
override fun onDisconnected(code: Int, reason: String) { /* 断开 */ }
override fun onMessage(msg: ImMessage) { /* 收到新消息 */ }
override fun onRevoke(msgId: String, operatorId: String) { /* 消息被撤回 */ }
override fun onError(t: Throwable) { /* 连接错误 */ }
}
// 连接
imClient.connect()
// 发送消息
imClient.send(SendMessageParams(
toId = "user_002",
chatType = ChatType.SINGLE,
msgType = MsgType.TEXT,
content = "Hello!"
))
// 撤回消息
imClient.revoke(msgId = "uuid")
// 断开连接（Activity/Fragment 销毁时调用）
imClient.disconnect()
```
### 消息类型（MsgType）
`TEXT` / `IMAGE` / `VIDEO` / `AUDIO` / `FILE` / `CUSTOM` / `LOCATION` / `NOTIFY` / `RICH_TEXT` / `CALL_AUDIO` / `CALL_VIDEO` / `FORWARD`
### ImMessage 结构
```kotlin
data class ImMessage(
val id: String,
val fromId: String,
val toId: String,
val chatType: ChatType, // SINGLE / GROUP
val msgType: MsgType,
val content: String,
val extra: String?,
val revoked: Boolean,
val createdAt: String
)
```
### 自动重连
断线后指数退避重连，初始间隔 3 秒，最大间隔 30 秒。调用 `disconnect()` 后停止重连。
---
## sdk-push
### 注册推送 Token
在获取到厂商推送 token 后调用：
```kotlin
PushSDK.registerToken(
appId = "ak_xxx",
userId = "user_001",
vendor = Vendor.HUAWEI, // HUAWEI / XIAOMI / OPPO / VIVO / HONOR / APNS
token = "device_push_token"
)
```
### 与 IM 联动
当 IM 和推送服务均已开启时，IM 服务在目标用户离线时会自动调用推送服务发送离线推送通知。
业务方只需分别注册推送 Token 和 IM 登录，无需额外配置。
---
## sdk-update
### 检查原生 App 更新
```kotlin
val result: UpdateResult = UpdateSDK.checkUpdate(
appId = "ak_xxx",
platform = Platform.ANDROID
)
if (result.needsUpdate) {
// result.versionName, result.downloadUrl, result.forceUpdate
UpdateSDK.downloadAndInstall(context, result.downloadUrl)
}
```
`downloadAndInstall` 会将 APK 下载到 `getExternalFilesDir(null)`，通过 `FileProvider` 触发系统安装。
AndroidManifest 中已配置 `@xml/file_paths`（`external-files-path`）。
### 检查 RN Bundle 更新
```kotlin
val rnResult = UpdateSDK.checkRnUpdate(
appId = "ak_xxx",
moduleId = "main",
platform = "android",
currentVersion = "1.0.0"
)
if (rnResult.needsUpdate) {
val filePath = UpdateSDK.downloadBundle(context, rnResult.downloadUrl, "main.android.bundle")
// 校验 MD5
// 通知 RN 引擎加载新 bundle
}
```
---
## 发版
```bash
# 在 gradle.properties 中配置 NEXUS_USER / NEXUS_PASSWORD
./gradlew :sdk-core:publish
./gradlew :sdk-im:publish
./gradlew :sdk-push:publish
./gradlew :sdk-update:publish
```
发布至 `https://nexus.xuqinmin.com/repository/android-hosted/`，groupId `com.xuqm`，版本号在各模块 `build.gradle.kts` 中维护。

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