docs: add detailed documentation

2026-04-21 22:25:35 +08:00 · 2026-04-21 22:25:35 +08:00 · 76aad3409f
--- a/README.md
+++ b/README.md
@ -0,0 +1,199 @@
+# XuqmGroup Vue3 SDK 文档
+
+> TypeScript · Vue 3.5 · Vite 6 · 发布至 Nexus npm
+
+## 安装
+
+```bash
+npm install @xuqm/vue3-sdk
+# 或
+yarn add @xuqm/vue3-sdk
+```
+
+Vue 3.5+ 作为 peerDependency，不会重复打包。
+
+## 目录结构
+
+```
+XuqmGroup-Vue3SDK/src/
+├── core/
+│   ├── http.ts     # fetch HTTP 客户端
+│   └── sdk.ts      # init / setToken / getConfig
+├── im/
+│   ├── ImClient.ts # WebSocket IM 客户端
+│   └── useIm.ts    # Vue Composable 封装
+├── types/
+│   └── index.ts    # 全部 TypeScript 类型定义
+└── index.ts        # 统一导出
+```
+
+---
+
+## 快速开始
+
+### 1. 初始化（main.ts）
+
+```typescript
+import { init } from '@xuqm/vue3-sdk'
+
+init({
+  appKey: 'ak_your_app_key',
+  appSecret: 'as_your_app_secret',
+  apiBaseUrl: 'https://api.xuqm.com',
+  imBaseUrl: 'wss://im.xuqm.com',
+  debug: import.meta.env.DEV,
+})
+```
+
+### 2. 设置 Token
+
+```typescript
+import { setToken } from '@xuqm/vue3-sdk'
+
+// 登录后
+setToken('eyJ...')
+
+// 登出
+setToken(null)
+```
+
+---
+
+## HTTP 客户端
+
+```typescript
+import { http } from '@xuqm/vue3-sdk'
+
+// 自动附加 Bearer Token，统一解析 ApiResponse
+const user = await http.get<UserInfo>('/api/user/profile')
+const result = await http.post<LoginResp>('/api/auth/login', { account, password })
+```
+
+---
+
+## IM 模块
+
+### useIm Composable（推荐）
+
+```vue
+<script setup lang="ts">
+import { useIm } from '@xuqm/vue3-sdk'
+
+const { connect, send, revoke, disconnect, messages, connected, error } = useIm()
+
+// 在 onMounted 后连接
+onMounted(() => connect())
+// onUnmounted 自动调用 disconnect()
+
+function handleSend(text: string) {
+  send({
+    toId: 'user_002',
+    chatType: 'SINGLE',
+    msgType: 'TEXT',
+    content: text,
+  })
+}
+</script>
+
+<template>
+  <div>
+    <span>{{ connected ? '已连接' : '未连接' }}</span>
+    <div v-for="msg in messages" :key="msg.id">
+      <b>{{ msg.fromId }}</b>: {{ msg.content }}
+    </div>
+  </div>
+</template>
+```
+
+### ImClient（底层，手动管理）
+
+```typescript
+import { ImClient } from '@xuqm/vue3-sdk'
+
+const im = new ImClient()
+
+im.on('connected', () => console.log('connected'))
+im.on('message', (msg) => console.log(msg))
+im.on('revoke', ({ msgId }) => console.log('revoked', msgId))
+im.on('disconnected', (code, reason) => console.log(code, reason))
+im.on('error', (e) => console.error(e))
+
+im.connect()
+
+// 发送
+im.send({ toId: 'user_002', chatType: 'SINGLE', msgType: 'TEXT', content: 'Hi!' })
+
+// 撤回
+im.revoke('msg-uuid')
+
+// 断开
+im.disconnect()
+```
+
+### 消息类型
+
+```typescript
+type MsgType =
+  | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'FILE'
+  | 'CUSTOM' | 'LOCATION' | 'NOTIFY' | 'RICH_TEXT'
+  | 'CALL_AUDIO' | 'CALL_VIDEO' | 'FORWARD'
+
+type ChatType = 'SINGLE' | 'GROUP'
+```
+
+### ImMessage 结构
+
+```typescript
+interface ImMessage {
+  id: string
+  fromId: string
+  toId: string
+  chatType: ChatType
+  msgType: MsgType
+  content: string
+  extra?: string
+  revoked: boolean
+  createdAt: string
+}
+```
+
+### 自动重连
+
+断线后指数退避重连：3s → 6s → 12s → 最大 30s。`disconnect()` 后停止，`useIm()` 在 `onUnmounted` 中自动调用。
+
+---
+
+## 完整类型导出
+
+```typescript
+import type {
+  SDKConfig,
+  ImMessage,
+  SendMessageParams,
+  ImEventMap,
+  MsgType,
+  ChatType,
+  ApiResponse,
+} from '@xuqm/vue3-sdk'
+```
+
+---
+
+## 构建
+
+```bash
+# 类型检查
+npm run type-check
+
+# 构建（输出 dist/index.es.js + dist/index.cjs.js + dist/index.d.ts）
+npm run build
+```
+
+## 发版
+
+```bash
+# 确认 .npmrc 指向 https://nexus.xuqinmin.com/repository/npm-hosted/
+npm login --registry=https://nexus.xuqinmin.com/repository/npm-hosted/
+npm run build
+npm publish
+```
--- a/docs/DEPLOY.md
+++ 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"}`
--- a/docs/PLATFORM_OVERVIEW.md
+++ 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 <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` |