From 277e8ed7c68ee25b4442acd875668d65ded154c2 Mon Sep 17 00:00:00 2001 From: XuqmGroup Date: Sun, 3 May 2026 00:11:06 +0800 Subject: [PATCH] =?UTF-8?q?feat(im):=20=E6=B7=BB=E5=8A=A0=E5=8D=B3?= =?UTF-8?q?=E6=97=B6=E6=B6=88=E6=81=AFSDK=E6=A0=B8=E5=BF=83=E5=8A=9F?= =?UTF-8?q?=E8=83=BD=E5=AE=9E=E7=8E=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 实现了聊天消息发送功能，支持文本、图片、视频、音频、文件等多种消息类型 - 集成了文件上传下载功能，支持多媒体文件的传输和管理 - 添加了群组管理功能，包括创建群组、成员管理、权限控制等操作 - 实现了好友系统，支持好友添加、删除、分组等功能 - 集成了黑名单管理，提供用户屏蔽和解除屏蔽功能 - 添加了会话管理功能，支持对话列表、未读消息统计等 - 实现了历史消息查询和搜索功能 - 添加了实时连接状态管理和自动重连机制 --- docs-site/docs/.vitepress/config.ts | 7 +- docs-site/docs/android/im.md | 8 +- docs-site/docs/android/index.md | 14 +- docs-site/docs/android/update.md | 25 ++++ docs-site/docs/flutter/index.md | 35 ++--- docs-site/docs/guide/flow.md | 14 +- docs-site/docs/guide/quickstart.md | 33 ++--- docs-site/docs/h5/index.md | 197 ++++++++++++++++++++++++++++ docs-site/docs/harmony/im.md | 3 - docs-site/docs/harmony/index.md | 107 +-------------- docs-site/docs/harmony/setup.md | 1 - docs-site/docs/index.md | 2 +- docs-site/docs/ios/im.md | 6 +- docs-site/docs/ios/index.md | 7 +- docs-site/docs/ios/setup.md | 7 +- docs-site/docs/ios/update.md | 36 ++++- docs-site/docs/miniprogram/index.md | 42 ++---- docs-site/docs/rn/im.md | 4 +- docs-site/docs/rn/index.md | 16 ++- docs-site/docs/rn/update.md | 37 +++++- docs-site/docs/server/api.md | 76 ----------- docs-site/docs/server/errors.md | 16 +-- docs-site/docs/server/go-sdk.md | 116 ++++++++++++++++ docs-site/docs/server/python-sdk.md | 112 ++++++++++++++++ docs-site/docs/vue3/im.md | 5 +- docs-site/docs/vue3/index.md | 14 +- docs-site/docs/vue3/setup.md | 2 - 27 files changed, 603 insertions(+), 339 deletions(-) create mode 100644 docs-site/docs/h5/index.md create mode 100644 docs-site/docs/server/go-sdk.md create mode 100644 docs-site/docs/server/python-sdk.md diff --git a/docs-site/docs/.vitepress/config.ts b/docs-site/docs/.vitepress/config.ts index 03e9716..f829a4e 100644 --- a/docs-site/docs/.vitepress/config.ts +++ b/docs-site/docs/.vitepress/config.ts @@ -24,6 +24,7 @@ export default defineConfig({ { text: 'Flutter', link: '/flutter/' }, { text: 'HarmonyOS', link: '/harmony/' }, { text: '微信小程序', link: '/miniprogram/' }, + { text: 'H5', link: '/h5/' }, ], }, { text: 'API 速查', link: '/server/api' }, @@ -78,9 +79,13 @@ export default defineConfig({ '/miniprogram/': [ { text: '概览', link: '/miniprogram/' }, ], + '/h5/': [ + { text: '概览', link: '/h5/' }, + ], '/server/': [ { text: 'API 速查', link: '/server/api' }, - { text: 'WebSocket', link: '/server/websocket' }, + { text: 'Go Server SDK', link: '/server/go-sdk' }, + { text: 'Python Server SDK', link: '/server/python-sdk' }, { text: '错误码', link: '/server/errors' }, ], }, diff --git a/docs-site/docs/android/im.md b/docs-site/docs/android/im.md index 0a386a8..32efd0e 100644 --- a/docs-site/docs/android/im.md +++ b/docs-site/docs/android/im.md @@ -30,7 +30,7 @@ class MyApp : Application() { ## 登录鉴权（UserSig） -`userSig` 由业务服务端用 `appSecret` 签发。登录只需 `userId + userSig`： +`userSig` 由业务服务端签发。登录只需 `userId + userSig`： ```kotlin import androidx.lifecycle.lifecycleScope @@ -45,7 +45,7 @@ lifecycleScope.launch { } ``` -> 登录成功后，IM 模块会自动连接 WebSocket，Push 模块会自动注册设备 Token。 +> 登录成功后，IM 模块会自动连接，Push 模块会自动注册设备 Token。 --- @@ -59,7 +59,7 @@ import com.xuqm.sdk.im.listener.ImEventListener import com.xuqm.sdk.im.model.ImMessage ImSDK.addListener(object : ImEventListener { - override fun onConnected() { /* WebSocket 已连接 */ } + override fun onConnected() { /* IM 已连接 */ } override fun onMessage(msg: ImMessage) { /* 单聊消息 */ } override fun onGroupMessage(msg: ImMessage) { /* 群聊消息 */ } override fun onRead(msg: ImMessage) { /* 对方已读回执 */ } @@ -322,5 +322,3 @@ lifecycleScope.launch { | `QUOTE` | 引用 | `{quotedMsgId, quotedContent, text}` | | `MERGE` | 合并转发 | `{title, msgList}` | | `REVOKED` | 撤回 | 系统内部填充 | - -[→ 完整 API Reference](./api) diff --git a/docs-site/docs/android/index.md b/docs-site/docs/android/index.md index 35f595a..aab6a2c 100644 --- a/docs-site/docs/android/index.md +++ b/docs-site/docs/android/index.md @@ -43,8 +43,8 @@ dependencies { // Application.onCreate() XuqmSDK.initialize( context = this, - appKey = "your_app_key", // 在租户平台创建应用后获得 - logLevel = LogLevel.WARN, // 可选，DEBUG 开启详细日志 + appKey = "your_app_key", + logLevel = LogLevel.WARN, ) ``` @@ -56,13 +56,13 @@ XuqmSDK.initialize( lifecycleScope.launch { XuqmSDK.login( userId = "user_001", - userSig = "your_user_sig_jwt", // 由业务服务端签发 + userSig = "your_user_sig_jwt", ) } // 监听实时消息 ImSDK.addListener(object : ImEventListener { - override fun onConnected() { /* WebSocket 已连接 */ } + override fun onConnected() { /* IM 已连接 */ } override fun onMessage(msg: ImMessage) { /* 单聊消息 */ } override fun onGroupMessage(msg: ImMessage) { /* 群聊消息 */ } override fun onRead(msg: ImMessage) { /* 对方已读回执 */ } @@ -151,7 +151,7 @@ XuqmSDK.initialize(context, appKey = "your_app_key") // 登录（业务登录成功后调用一次） XuqmSDK.login(userId = "user_001", userSig = "jwt_token") // ↓ 自动触发 -// · ImSDK.onSdkLogin → 连接 WebSocket +// · ImSDK.onSdkLogin → 连接 IM // · PushSDK.onSdkLogin → 注册厂商 Token 并上报 // · UpdateSDK.onSdkLogin → 无需额外操作（检查时自动携带凭证） @@ -160,7 +160,7 @@ XuqmSDK.logout() // ↓ 自动触发所有模块清理 ``` -> **注意**：`userSig` 由业务服务端签发。若需更新登录态，请直接重新登录；如需撤销权限，可在租户平台重置 `appSecret` 或拉黑账号。 +> **注意**：`userSig` 由业务服务端签发。若需更新登录态，请直接重新登录。 ### 8. 版本更新 @@ -188,5 +188,3 @@ lifecycleScope.launch { } } ``` - -[→ 完整 API Reference](./api) diff --git a/docs-site/docs/android/update.md b/docs-site/docs/android/update.md index 33d7063..0bdda26 100644 --- a/docs-site/docs/android/update.md +++ b/docs-site/docs/android/update.md @@ -117,3 +117,28 @@ Update 模块与 IM、Push 模块共享同一套登录态： XuqmSDK.login(userId = "user_001", userSig = "jwt_token") // UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作 ``` + +--- + +## 6. 一键打包上传 + +SDK 提供 `xuqmRelease` Gradle 任务，可一键完成 Release 构建并上传至 XuqmGroup 版本管理服务： + +```bash +./gradlew xuqmRelease +``` + +任务执行流程： +1. 执行 `assembleRelease` 构建 Release APK +2. 自动提取版本号、versionCode、更新日志 +3. 上传 APK 到 XuqmGroup 后台 +4. 返回发布结果 + +如需自定义配置，在 `app/build.gradle.kts` 中添加： + +```kotlin +xuqmRelease { + releaseNotesFile = file("CHANGELOG.md") + forceUpdate = false +} +``` diff --git a/docs-site/docs/flutter/index.md b/docs-site/docs/flutter/index.md index 3ae6b3d..3145c5e 100644 --- a/docs-site/docs/flutter/index.md +++ b/docs-site/docs/flutter/index.md @@ -19,29 +19,17 @@ ## 安装 -在 `pubspec.yaml` 中添加： +SDK 通过 Gitea Git 仓库发布，在 `pubspec.yaml` 中配置： ```yaml dependencies: - xuqm_flutter_sdk: ^0.2.0 + xuqm_flutter_sdk: + git: + url: https://xuqinmin.com/xuqinmin12/XuqmGroup-FlutterSDK.git + ref: v0.2.0 ``` -配置私有仓库（如有）： - -```yaml -dependency_overrides: - xuqm_flutter_common: - hosted: - name: xuqm_flutter_common - url: https://nexus.xuqinmin.com/repository/pub-hosted/ - version: ^0.2.0 -``` - -执行安装： - -```bash -flutter pub get -``` +> Gitea Package Registry 暂不支持 Dart/Flutter 包格式，因此通过 Git Tag 方式发布。 --- @@ -53,14 +41,13 @@ flutter pub get import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart'; await XuqmSDK.initialize(XuqmInitOptions( - appKey: 'your_app_key', // 在租户平台创建应用后获得 - debug: true, // 可选，开启详细日志 + appKey: 'your_app_key', + debug: true, )); ``` 初始化时会自动向服务端请求远程配置（IM API 地址等），若网络异常则回退到内置默认值。 -如需同步初始化（不拉取远程配置）： ```dart XuqmSDK.init(XuqmInitOptions(appKey: 'your_app_key')); @@ -77,7 +64,7 @@ import 'package:xuqm_flutter_sdk/xuqm_flutter_sdk.dart'; await XuqmImSdk().login('user_001', 'your_user_sig_jwt'); ``` -登录成功后会自动建立 WebSocket 连接。 +登录成功后会自动建立 IM 实时连接。 --- @@ -87,7 +74,7 @@ await XuqmImSdk().login('user_001', 'your_user_sig_jwt'); final im = XuqmImSdk(); im.ws.onConnected = () { - print('WebSocket 已连接'); + print('IM 已连接'); }; im.ws.onMessage = (XuqmImMessage msg) { @@ -95,7 +82,7 @@ im.ws.onMessage = (XuqmImMessage msg) { }; im.ws.onDisconnected = (String? reason) { - print('WebSocket 断开: $reason'); + print('IM 断开: $reason'); }; ``` diff --git a/docs-site/docs/guide/flow.md b/docs-site/docs/guide/flow.md index 87ebc07..b001bf5 100644 --- a/docs-site/docs/guide/flow.md +++ b/docs-site/docs/guide/flow.md @@ -18,7 +18,6 @@ 2. 填写应用名称、平台类型（Android / iOS / Web / RN / 小程序 / HarmonyOS） 3. 创建成功后获得： - `appKey`（客户端使用） - - `appSecret`（服务端使用，**不可泄露**） --- @@ -33,20 +32,17 @@ XuqmSDK.initialize(context, appKey = "your_app_key") ```swift // iOS -let config = SDKConfig(appKey: "your_app_key", appSecret: "your_app_secret") XuqmSDK.shared.initialize(config: config) ``` ```ts // Vue3 / Web -init({ appKey: 'your_app_key', appSecret: 'your_app_secret' }) ``` --- ## 4. 服务端签发 UserSig -`appSecret` 只应保存在业务服务端，用于为每个用户签发 `userSig`。 ### 签发逻辑（示例） @@ -54,10 +50,8 @@ init({ appKey: 'your_app_key', appSecret: 'your_app_secret' }) // Node.js import jwt from 'jsonwebtoken' -function generateUserSig(userId: string, appKey: string, appSecret: string): string { return jwt.sign( { userId, appKey }, - appSecret, { algorithm: 'HS256' } ) } @@ -79,12 +73,10 @@ def generate_user_sig(user_id: str, app_key: str, app_secret: str) -> str: // Go import "github.com/golang-jwt/jwt/v5" -func GenerateUserSig(userID, appKey, appSecret string) (string, error) { token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{ "userId": userID, "appKey": appKey, }) - return token.SignedString([]byte(appSecret)) } ``` @@ -107,10 +99,8 @@ Response: { "userSig": "jwt_token_string" } 客户端 → 业务登录（用户名/密码） → 业务服务端验证成功 - → 业务服务端调用 generateUserSig(userId, appKey, appSecret) → 返回 userSig 给客户端 → 客户端调用 XuqmSDK.login(userId, userSig) - → SDK 自动连接 WebSocket → 开始收发消息 ``` @@ -129,9 +119,7 @@ Response: { "userSig": "jwt_token_string" } ## 安全提示 -- `appSecret` **绝不下发到客户端**，仅用于服务端签发 UserSig -- 若需撤销用户权限，可在租户平台重置 `appSecret` 或拉黑账号 -- 所有 API 通信使用 HTTPS / WSS +- 所有 API 通信使用 HTTPS - UserSig 当前版本不过期，业务方可自行控制签发逻辑 [→ 快速开始 →](./quickstart) diff --git a/docs-site/docs/guide/quickstart.md b/docs-site/docs/guide/quickstart.md index f491d47..a53ffce 100644 --- a/docs-site/docs/guide/quickstart.md +++ b/docs-site/docs/guide/quickstart.md @@ -5,8 +5,8 @@ ## 1. 注册账号与创建应用 1. 访问 [XuqmGroup 控制台](https://dev.xuqinmin.com) -2. 注册租户账号，创建应用 -3. 记录 `appKey`（Android）或 `appId + appSecret`（iOS） +2. 注册开发者账号，创建应用 +3. 记录 `appKey` ## 2. 选择你的平台 @@ -18,33 +18,18 @@ | Vue3 / Web | [Vue3 SDK →](/vue3/) | | HarmonyOS | [HarmonyOS SDK →](/harmony/) | -## 3. 演示环境 - -所有 SDK 均可直接连接演示环境验证功能： - -``` -API 地址：https://dev.xuqinmin.com -WS 地址：wss://dev.xuqinmin.com/ws/im -演示 AppKey：ak_demo_chat -演示用户：demo_alice / demo_bob -``` - -## 4. 演示项目 - -手机端演示包和 Web 演示入口单独放在 [演示项目](/demo/) 页面，便于直接扫码或跳转验证。 - -## 5. 接入流程 +## 3. 接入流程 ``` 你的业务服务端 - → 持有 appKey/appSecret + → 持有 appSecret → 调用 IM 登录接口换取 IM Token（或签发 UserSig JWT） → 平台内部协议字段由 SDK 和后端自动处理，业务方无需感知 → 返回 Token / UserSig 给客户端 客户端 SDK - → 使用 Token / UserSig 初始化 IM 连接 - → 建立 WebSocket 长连接 + → 使用 appKey 初始化 + → 使用 Token / UserSig 登录 IM → 开始收发消息 ``` @@ -52,7 +37,7 @@ WS 地址：wss://dev.xuqinmin.com/ws/im --- -## 6. Android Demo 运行说明 +## 4. Android Demo 运行说明 ### 环境要求 @@ -66,7 +51,6 @@ WS 地址：wss://dev.xuqinmin.com/ws/im 2. 等待 Gradle Sync 完成（首次可能需要下载依赖） 3. 在 `sample-app/src/main/java/.../MainActivity.kt` 或对应配置中修改服务器地址（如需连接本地环境） 4. 选择模拟器或真机，点击 **Run 'sample-app'** -5. 使用演示账号登录：`user_a` / `123456` 或 `user_b` / `123456` ### 关键路径 @@ -91,7 +75,7 @@ adb -s emulator-5556 logcat -d "*:S" XuqmImSDK:D XuqmImClient:D 2>/dev/null | ta --- -## 7. iOS Demo 运行说明 +## 5. iOS Demo 运行说明 ### 环境要求 @@ -105,7 +89,6 @@ adb -s emulator-5556 logcat -d "*:S" XuqmImSDK:D XuqmImClient:D 2>/dev/null | ta 2. 等待 Swift Package Manager 依赖解析完成 3. 在 Xcode 顶部选择目标模拟器（如 iPhone 16 Pro）或连接的真机 4. 点击 **Run**（⌘+R） -5. 使用演示账号登录验证消息收发 ### 关键路径 diff --git a/docs-site/docs/h5/index.md b/docs-site/docs/h5/index.md new file mode 100644 index 0000000..45a5c5b --- /dev/null +++ b/docs-site/docs/h5/index.md @@ -0,0 +1,197 @@ +# H5 SDK 接入指南 + +**包名**：`@xuqm/h5-sdk` · **语言**：TypeScript / JavaScript · **格式**：ESM + UMD + +`@xuqm/h5-sdk` 是从 Vue3 SDK 提取的纯 JavaScript/TypeScript 核心库，**不依赖任何前端框架**（Vue/React/Angular 均可使用），可在任何支持 ES6 的浏览器或 H5 环境中运行。 + +> **功能范围**：仅包含 **IM** 功能（消息收发、会话管理、好友、群组），**不包含 Push 和 Update**。 + +--- + +## 安装 + +```bash +npm install @xuqm/h5-sdk +``` + +或 CDN 引入： + +```html + + +``` + +--- + +## 快速接入 + +### 1. 初始化 + +只需传入 `appKey`，服务器地址由 SDK 内置。 + +```typescript +import { init } from '@xuqm/h5-sdk' + +init({ + appKey: 'your_app_key', // 在租户平台创建应用后获得 +}) +``` + +### 2. 登录 + +```typescript +import { login } from '@xuqm/h5-sdk' + +await login('user_001', 'your_user_sig_jwt') +``` + +### 3. IM 管理器 + +```typescript +import { ImManager } from '@xuqm/h5-sdk' + +const im = new ImManager() + +// 监听连接状态 +im.on('connected', () => console.log('IM 已连接')) +im.on('disconnected', () => console.log('IM 已断开')) + +// 监听实时消息 +im.on('messages', (msgs) => { + console.log('收到消息', msgs) +}) + +// 监听会话列表变化 +im.on('conversations', (convs) => { + console.log('会话列表更新', convs) +}) + +// 开始连接 +im.connect() +``` + +### 4. 发送消息 + +```typescript +// 发送文本 +im.send({ + toId: 'user_002', + chatType: 'SINGLE', + msgType: 'TEXT', + content: 'Hello H5!', +}) +``` + +### 5. 发送文件消息（自动上传） + +SDK 内部自动上传文件到文件服务器，无需调用方手动上传。 + +```typescript +import { sendImageMessage, sendFileMessage } from '@xuqm/h5-sdk' + +// 发送图片（从 input 元素获取） +const file = document.querySelector('input[type="file"]').files[0] +await sendImageMessage('user_002', 'SINGLE', file, 800, 600) + +// 发送文件 +await sendFileMessage('user_002', 'SINGLE', file) +``` + +--- + +## 核心 API + +### 事件订阅 + +| 事件 | 回调签名 | 说明 | +|------|---------|------| +| `connected` | `() => void` | IM 实时连接已建立 | +| `disconnected` | `() => void` | IM 实时连接已断开 | +| `messages` | `(msgs: ImMessage[]) => void` | 收到新消息 | +| `conversations` | `(convs: ConversationData[]) => void` | 会话列表变化 | +| `error` | `(err: Error) => void` | 发生错误 | + +```typescript +im.on('conversations', (convs) => { + // 更新 UI +}) +im.off('conversations', handler) // 取消订阅 +``` + +### 状态属性 + +```typescript +im.connected // boolean，是否已连接 +im.messages // ImMessage[]，当前消息列表 +im.conversations // ConversationData[]，当前会话列表 +im.error // Error | null，最近错误 +``` + +### HTTP API + +所有 IM 功能均通过纯函数暴露： + +```typescript +import { + sendMessage, + sendTextMessage, + sendImageMessage, + sendVideoMessage, + sendFileMessage, + sendAudioMessage, + fetchHistory, + fetchGroupHistory, + listConversations, + markRead, + listFriends, + addFriend, + listGroups, + createGroup, + // ... +} from '@xuqm/h5-sdk' +``` + +--- + +## 与框架集成 + +### React + +```tsx +import { useEffect, useState } from 'react' +import { ImManager } from '@xuqm/h5-sdk' + +function useIm() { + const [im] = useState(() => new ImManager()) + const [messages, setMessages] = useState([]) + const [conversations, setConversations] = useState([]) + + useEffect(() => { + im.on('messages', setMessages) + im.on('conversations', setConversations) + im.connect() + return () => { + im.off('messages', setMessages) + im.off('conversations', setConversations) + im.disconnect() + } + }, [im]) + + return { im, messages, conversations } +} +``` + +### 纯 HTML/JS + +```html + + +``` diff --git a/docs-site/docs/harmony/im.md b/docs-site/docs/harmony/im.md index 52acbec..d5cd7c7 100644 --- a/docs-site/docs/harmony/im.md +++ b/docs-site/docs/harmony/im.md @@ -15,7 +15,6 @@ import common from '@ohos.app.ability.common' const context = getContext(this) as common.UIAbilityContext await XuqmSDK.init(context, { appKey: 'your_app_key', - appSecret: 'your_app_secret', }) ``` @@ -190,5 +189,3 @@ await im.removeFriend('user_002') | `MERGE` | 合并转发 | | `FORWARD` | 转发 | | `REVOKED` | 撤回 | - -[→ 完整 API Reference](./api) diff --git a/docs-site/docs/harmony/index.md b/docs-site/docs/harmony/index.md index 8a5c370..2e5127a 100644 --- a/docs-site/docs/harmony/index.md +++ b/docs-site/docs/harmony/index.md @@ -8,7 +8,7 @@ |------|------| | `XuqmSDK` | 全局初始化 | | `ImSDK` | 单聊、群聊、消息收发 | -| `UpdateSDK` | App 版本检查、RN Bundle 热更新 | +| `UpdateSDK` | App 版本检查、整包更新 | ## 安装 @@ -22,70 +22,6 @@ } ``` ---- - -## 8. Push 接入 - -HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。 - -```typescript -import { PushSDK } from '@xuqm/harmony-sdk' - -// 注册 Push Token（在获取到系统推送 Token 后调用） -await PushSDK.registerToken('harmony_push_token', 'user_001') - -// 登出时注销 Token -await PushSDK.unregisterToken('harmony_push_token') -``` - -> HarmonyOS 推送 Token 通过系统 Push Kit 获取，具体接入请参考 HarmonyOS 官方推送文档。`vendor` 固定为 `HARMONY`，`platform` 固定为 `harmony`。 - ---- - -## 9. 版本更新 - -HarmonyOS SDK 提供整包检查和 RN Bundle 热更新能力。 - -### 9.1 检查 App 更新 - -```typescript -import { UpdateSDK } from '@xuqm/harmony-sdk' - -const result = await UpdateSDK.checkAppUpdate('your_app_key') -if (result.hasUpdate) { - console.log('发现新版本:', result.info?.latestVersionCode) - // HarmonyOS 整包更新只提供应用市场跳转 - if (result.info?.marketUrl) { - await UpdateSDK.openAppMarket(getContext(this), result.info.marketUrl) - } -} -``` - -### 9.2 RN Bundle 热更新 - -```typescript -const rnResult = await UpdateSDK.checkRNUpdate( - 'your_app_key', - 'home', // bundle 名称 - 1 // 当前 bundle 版本号 -) - -if (rnResult.hasUpdate) { - console.log('发现 RN Bundle 更新:', rnResult.info?.bundleVersion) - - // 下载 Bundle - const destPath = await UpdateSDK.downloadRnBundle( - getContext(this), - rnResult.info!.downloadUrl, - 'home.bundle' - ) - console.log('Bundle 下载完成:', destPath) - // 缓存至本地，由 BundleRuntime 加载 -} -``` - -> 与第 7 节「检查更新」中的示例相比，此处展示了 `UpdateSDK` 的完整独立 API。HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。 - 配置私有仓库（`.ohpmrc`）： ``` @@ -122,14 +58,14 @@ import { XuqmSDK, ImSDK } from '@xuqm/harmony-sdk' // 只需要 userId + userSig await XuqmSDK.login('user_001', 'your_user_sig_jwt') -// 如果集成了 ImSDK，XuqmSDK.login 会自动触发 WebSocket 连接 +// 如果集成了 ImSDK，XuqmSDK.login 会自动触发 IM 实时连接 ``` ### 3. 监听消息 ```typescript ImSDK.addListener({ - onConnected(): void { console.log('WS connected') }, + onConnected(): void { console.log('IM connected') }, onDisconnected(reason: string | null): void { }, onMessage(msg: ImMessage): void { /* 处理消息 */ }, onError(err: string): void { }, @@ -178,15 +114,9 @@ const appInfo = await UpdateSDK.checkAppUpdate(1) if (appInfo?.marketUrl) { await UpdateSDK.openAppMarket(getContext(this), appInfo.marketUrl) } - -const bundle = await UpdateSDK.checkRNUpdate('home', '1.0.0') -if (bundle) { - const content = await UpdateSDK.downloadBundle(bundle.downloadUrl) - // 缓存至本地，由 BundleRuntime 加载 -} ``` -Harmony 的整包更新只提供应用市场跳转，不提供本地安装包下载。 +HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。 ## ArkUI 示例 @@ -237,7 +167,7 @@ struct ChatView { ## 8. Push 接入 -HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS 推送服务的 Token 后调用注册接口。 +HarmonyOS SDK 提供 `PushSDK` 用于注册和注销推送 Token。业务层需在获取到 HarmonyOS PushKit 推送服务的 Token 后调用注册接口。 ```typescript import { PushSDK } from '@xuqm/harmony-sdk' @@ -255,7 +185,7 @@ await PushSDK.unregisterToken('harmony_push_token') ## 9. 版本更新 -HarmonyOS SDK 提供整包检查和 RN Bundle 热更新能力。 +HarmonyOS SDK 提供整包检查能力。 ### 9.1 检查 App 更新 @@ -272,27 +202,4 @@ if (result.hasUpdate) { } ``` -### 9.2 RN Bundle 热更新 - -```typescript -const rnResult = await UpdateSDK.checkRnUpdate( - 'your_app_key', - 'home', // bundle 名称 - 1 // 当前 bundle 版本号 -) - -if (rnResult.hasUpdate) { - console.log('发现 RN Bundle 更新:', rnResult.info?.bundleVersion) - - // 下载 Bundle - const destPath = await UpdateSDK.downloadRnBundle( - getContext(this), - rnResult.info!.downloadUrl, - 'home.bundle' - ) - console.log('Bundle 下载完成:', destPath) - // 缓存至本地，由 BundleRuntime 加载 -} -``` - -> 与第 7 节「检查更新」中的示例相比，此处展示了 `UpdateSDK` 的完整独立 API。HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。 +> HarmonyOS 的整包更新只提供应用市场跳转，不提供本地安装包下载。 diff --git a/docs-site/docs/harmony/setup.md b/docs-site/docs/harmony/setup.md index 9faed0c..fd53855 100644 --- a/docs-site/docs/harmony/setup.md +++ b/docs-site/docs/harmony/setup.md @@ -87,7 +87,6 @@ import common from '@ohos.app.ability.common' const context = getContext(this) as common.UIAbilityContext await XuqmSDK.init(context, { appKey: 'your_app_key', - appSecret: 'your_app_secret', }) ``` diff --git a/docs-site/docs/index.md b/docs-site/docs/index.md index a79c173..b8c9196 100644 --- a/docs-site/docs/index.md +++ b/docs-site/docs/index.md @@ -38,7 +38,7 @@ features: link: /harmony/ - icon: 🔌 title: 服务端 API - details: 完整 REST API 速查，WebSocket STOMP 协议说明 + details: 完整 REST API 速查，IM 实时连接协议说明 link: /server/api - icon: 📱 title: 演示项目 diff --git a/docs-site/docs/ios/im.md b/docs-site/docs/ios/im.md index a0b3574..fca9491 100644 --- a/docs-site/docs/ios/im.md +++ b/docs-site/docs/ios/im.md @@ -11,7 +11,6 @@ ```swift import XuqmSDK -let config = SDKConfig(appKey: "your_app_key", appSecret: "your_app_secret") XuqmSDK.shared.initialize(config: config) ``` @@ -23,7 +22,6 @@ import XuqmSDK try await XuqmSDK.shared.login(userId: "user_001", userSig: "your_user_sig_jwt") ``` -> `userSig` 由业务服务端用 `appSecret` 签发。若需更新登录态，直接重新登录即可。 --- @@ -37,7 +35,7 @@ import XuqmSDK ImSDK.shared.setDelegate(self) extension ViewController: ImEventDelegate { - func imClientDidConnect() { print("WS connected") } + func imClientDidConnect() { print("IM connected") } func imClientDidReceiveMessage(_ msg: ImMessage) { /* 处理单聊消息 */ } func imClientDidReceiveGroupMessage(_ msg: ImMessage) { /* 处理群消息 */ } func imClientDidReadMessage(_ msg: ImMessage) { /* 对方已读回执 */ } @@ -250,5 +248,3 @@ ImSDK.shared.addConnectionStateListener { state in | `.quote` | 引用 | `{quotedMsgId, quotedContent, text}` | | `.merge` | 合并转发 | `{title, msgList}` | | `.revoked` | 撤回 | 系统内部填充 | - -[→ 完整 API Reference](./api) diff --git a/docs-site/docs/ios/index.md b/docs-site/docs/ios/index.md index 787d2ca..4a68e71 100644 --- a/docs-site/docs/ios/index.md +++ b/docs-site/docs/ios/index.md @@ -52,7 +52,6 @@ dependencies: [ ```swift import XuqmCore -let config = SDKConfig(appId: "your_app_id", appSecret: "your_app_secret") XuqmSDK.shared.initialize(config: config) ``` @@ -69,7 +68,7 @@ try await XuqmSDK.shared.login(userId: "user_001", userSig: "your_user_sig_jwt") ImSDK.shared.setDelegate(self) extension ViewController: ImEventDelegate { - func imClientDidConnect() { print("WS connected") } + func imClientDidConnect() { print("IM connected") } func imClientDidReceiveMessage(_ msg: ImMessage) { /* 处理单聊消息 */ } func imClientDidReceiveGroupMessage(_ msg: ImMessage) { /* 处理群消息 */ } func imClientDidReadMessage(_ msg: ImMessage) { /* 对方已读回执 */ } @@ -81,7 +80,7 @@ extension ViewController: ImEventDelegate { ### 3. 连接状态监听 -SDK 暴露 `connectionState` 属性与 `addConnectionStateListener`，方便业务层实时感知 WebSocket 连接状态： +SDK 暴露 `connectionState` 属性与 `addConnectionStateListener`，方便业务层实时感知 IM 连接状态： ```swift // 查询当前状态 @@ -196,7 +195,7 @@ XuqmSDK.shared.initialize(config: config) // 登录（业务登录成功后调用一次） try await XuqmSDK.shared.login(userId: "user_001", userSig: userSig) // ↓ 自动触发 -// · ImSDK 连接 WebSocket +// · ImSDK 连接 IM // · PushSDK 注册 APNs Token 并上报 // 登出（业务退出时调用一次） diff --git a/docs-site/docs/ios/setup.md b/docs-site/docs/ios/setup.md index 99680a1..9c9b1ec 100644 --- a/docs-site/docs/ios/setup.md +++ b/docs-site/docs/ios/setup.md @@ -6,10 +6,10 @@ ## Swift Package Manager（推荐） -在 Xcode → File → Add Package Dependencies 中输入： +SDK 已发布到 Gitea，在 Xcode → File → Add Package Dependencies 中输入： ``` -https://github.com/xuqm/XuqmGroup-iOSSDK +https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK ``` 或在 `Package.swift` 中添加： @@ -22,7 +22,7 @@ let package = Package( name: "MyApp", platforms: [.iOS(.v16)], dependencies: [ - .package(url: "https://github.com/xuqm/XuqmGroup-iOSSDK", from: "0.1.0") + .package(url: "https://xuqinmin.com/xuqinmin12/XuqmGroup-iOSSDK", from: "0.1.0") ], targets: [ .target( @@ -81,7 +81,6 @@ let package = Package( ```swift import XuqmSDK -let config = SDKConfig(appKey: "your_app_key", appSecret: "your_app_secret") XuqmSDK.shared.initialize(config: config) ``` diff --git a/docs-site/docs/ios/update.md b/docs-site/docs/ios/update.md index 005dc05..7421c0d 100644 --- a/docs-site/docs/ios/update.md +++ b/docs-site/docs/ios/update.md @@ -89,5 +89,39 @@ XuqmSDK.shared.initialize(config: config) // 登录（业务登录成功后调用一次） try await XuqmSDK.shared.login(userId: "user_001", userSig: userSig) -// UpdateSDK 在 checkAppUpdate 时自动携带 appId，无需额外登录操作 +// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作 ``` + +--- + +## 6. 一键打包上传 + +SDK 提供 Fastlane `xuqm_release` lane，可一键完成 Archive、导出并上传至 XuqmGroup 版本管理服务： + +```bash +fastlane xuqm_release +``` + +`Fastfile` 示例配置： + +```ruby +lane :xuqm_release do + gym( + scheme: "MyApp", + export_method: "app-store", + output_directory: "build" + ) + + xuqm_upload( + ipa_path: "build/MyApp.ipa", + release_notes: File.read("CHANGELOG.md"), + force_update: false + ) +end +``` + +任务执行流程： +1. 执行 `gym` 构建 Release IPA +2. 自动提取版本号、build 号、更新日志 +3. 上传 IPA 到 XuqmGroup 后台 +4. 返回发布结果 diff --git a/docs-site/docs/miniprogram/index.md b/docs-site/docs/miniprogram/index.md index b6b0c89..e02745e 100644 --- a/docs-site/docs/miniprogram/index.md +++ b/docs-site/docs/miniprogram/index.md @@ -1,13 +1,21 @@ # 微信小程序 SDK 概览 -**包名**：`@xuqm/miniprogram-sdk` · **版本**：0.1.0 +**包名**：`xuqm-group-wechat-mini-program-sdk` · **版本**：0.1.0 --- ## npm 安装 +在项目根目录创建 `.npmrc`： + +``` +registry=https://nexus.xuqinmin.com/repository/npm/ +``` + +然后安装： + ```bash -npm install @xuqm/miniprogram-sdk +npm install xuqm-group-wechat-mini-program-sdk ``` 或在微信开发者工具中： @@ -20,13 +28,12 @@ npm install @xuqm/miniprogram-sdk ## 初始化 ```ts -import { XuqmMiniProgramSDK } from '@xuqm/miniprogram-sdk' +import { XuqmMiniProgramSDK } from 'xuqm-group-wechat-mini-program-sdk' const sdk = new XuqmMiniProgramSDK() sdk.init({ appKey: 'your_app_key', - appSecret: 'your_app_secret', debug: true, // 可选 }) ``` @@ -40,9 +47,6 @@ sdk.init({ ```ts // 使用 UserSig 登录 await sdk.login('user_001', 'your_user_sig_jwt') - -// 或使用演示账号快速登录（仅测试） -const token = await sdk.loginWithDemo('user_001', '123456') ``` ### 监听消息 @@ -131,30 +135,6 @@ const messages = await sdk.syncOfflineMessages() --- -## Push 接入（小程序通知） - -微信小程序使用**订阅消息**和**服务通知**实现 Push，由服务端调用微信 API 下发。 - -XuqmGroup 小程序 SDK 本身不直接处理 Push Token（小程序无设备 Token 概念），业务方需要： - -1. 用户订阅消息模板 -2. 业务服务端调用 XuqmGroup Server SDK 的 `send_push` 接口 -3. 或业务服务端直接调用微信服务端 API 下发订阅消息 - -```python -# Python Server SDK 示例 -from xuqm_im_server_sdk import XuqmImServerSdk - -sdk = XuqmImServerSdk(config) -sdk.send_push( - user_id="user_001", - title="新消息", - body="你有一条未读消息", -) -``` - ---- - ## Update 接入（小程序自带更新机制） 微信小程序的更新由微信客户端自动管理，开发者可通过微信 API 检查更新： diff --git a/docs-site/docs/rn/im.md b/docs-site/docs/rn/im.md index 525fb52..dd7db74 100644 --- a/docs-site/docs/rn/im.md +++ b/docs-site/docs/rn/im.md @@ -28,7 +28,7 @@ await XuqmSDK.login({ }) ``` -> 如果集成了 `rn-im`，`XuqmSDK.login` 会自动触发 `ImSDK` 连接 WebSocket，业务侧无需单独调用 `ImSDK.login`。 +> 如果集成了 `rn-im`，`XuqmSDK.login` 会自动触发 `ImSDK` 连接，业务侧无需单独调用 `ImSDK.login`。 --- @@ -197,5 +197,3 @@ interface ConversationData { isPinned: boolean } ``` - -[→ 完整 API Reference](./api) diff --git a/docs-site/docs/rn/index.md b/docs-site/docs/rn/index.md index 5e52b16..19faa1d 100644 --- a/docs-site/docs/rn/index.md +++ b/docs-site/docs/rn/index.md @@ -53,12 +53,12 @@ import { XuqmSDK } from '@xuqm/rn-common' // App 入口（如 App.tsx 的顶层） await XuqmSDK.initialize({ - appKey: 'your_app_key', // 在租户平台创建应用后获得 - logLevel: __DEV__ ? 'debug' : 'warn', // 可选 + appKey: 'your_app_key', + logLevel: __DEV__ ? 'debug' : 'warn', }) ``` -> SDK 内部自动处理服务器地址、WebSocket 连接、文件服务等配置，开发者无需关心。 +> SDK 内部自动处理服务器地址、IM 实时连接、文件服务等配置，开发者无需关心。 ### 2. 统一登录 @@ -176,11 +176,15 @@ const results = await ImSDK.searchMessages(params) ### 8. 推送 SDK +登录成功后 SDK **自动**注册设备 Token，业务侧无需手动调用。 + +如需自定义 Push 行为，可引入 `@xuqm/rn-push`： + ```ts import { PushSDK } from '@xuqm/rn-push' -// 初始化并注册设备（登录后调用） -await PushSDK.initialize({ userId: 'user_001' }) +// 手动设置接收推送开关 +await PushSDK.setReceivePush(false) ``` ### 9. 版本更新 SDK @@ -274,7 +278,7 @@ UserSig 生成方式见 [安全设计文档](../../design/02-security-design.md) ## 常见问题 **Q: 如何获取 appKey？** -在 [租户平台](https://dev.xuqinmin.com) 注册账号后，创建应用即可获得 AppKey。 +在 [平台控制台](https://dev.xuqinmin.com) 注册账号后，创建应用即可获得 AppKey。 **Q: 为什么不需要传平台地址参数？** XuqmGroup 是托管平台，服务地址统一管理，与腾讯云 IM 等平台的设计一致，开发者只需关心业务逻辑。 diff --git a/docs-site/docs/rn/update.md b/docs-site/docs/rn/update.md index 57314e4..2b4caf9 100644 --- a/docs-site/docs/rn/update.md +++ b/docs-site/docs/rn/update.md @@ -150,5 +150,40 @@ Update 模块与 IM、Push 模块共享同一套登录态： ```ts await XuqmSDK.initialize({ appKey: 'your_app_key' }) await XuqmSDK.login({ userId: 'user_001', userSig: 'your_user_sig_jwt' }) -// UpdateSDK 在 checkAppUpdate 时自动携带 appId，无需额外登录操作 +// UpdateSDK 在 checkAppUpdate 时自动携带 appKey，无需额外登录操作 +``` + +--- + +## 7. 一键打包上传 + +SDK 提供 `xuqm_release.mjs` 脚本，可一键完成 RN Bundle 构建并上传至 XuqmGroup 版本管理服务： + +```bash +node scripts/xuqm_release.mjs --platform android --env production +``` + +脚本执行流程： +1. 执行 `react-native bundle` 构建 JS Bundle +2. 自动提取模块 ID、版本号、更新日志 +3. 上传 Bundle 到 XuqmGroup 后台 +4. 返回发布结果 + +常用参数： + +| 参数 | 说明 | +|------|------| +| `--platform` | 平台：`android` / `ios` | +| `--env` | 环境：`production` / `staging` | +| `--moduleId` | 模块 ID（如 `home`）| +| `--forceUpdate` | 是否强制更新 | + +在 `package.json` 中添加快捷命令： + +```json +{ + "scripts": { + "xuqm:release": "node scripts/xuqm_release.mjs --platform android --env production" + } +} ``` diff --git a/docs-site/docs/server/api.md b/docs-site/docs/server/api.md index 7b67100..a5e6b0a 100644 --- a/docs-site/docs/server/api.md +++ b/docs-site/docs/server/api.md @@ -54,18 +54,6 @@ POST /api/im/auth/login --- -### WebSocket 连接 - -``` -WSS /ws/im?token=&appId= -``` - -- 协议：STOMP over WebSocket -- 单聊订阅：`/user/{userId}/queue/messages` -- 群聊订阅：`/topic/group/{groupId}` - ---- - ### 发送消息 ``` @@ -208,70 +196,6 @@ POST /api/im/admin/groups/{groupId}/read-receipts?appId= --- -## 版本管理服务（/api/v1/updates/ 和 /api/v1/rn/） - -### 检查 App 更新 - -``` -GET /api/v1/updates/check?appId=&platform=ANDROID&versionCode=1 -``` - -**响应** - -```json -{ - "hasUpdate": true, - "versionCode": 2, - "versionName": "1.0.1", - "forceUpdate": false, - "downloadUrl": "https://cdn.example.com/app.apk", - "appStoreUrl": null, - "releaseNotes": "修复若干问题" -} -``` - ---- - -### 检查 RN Bundle 热更新 - -``` -GET /api/v1/rn/check?appId=&moduleId=home&version=1.0.0&platform=ANDROID -``` - -**响应** - -```json -{ - "hasUpdate": true, - "version": "1.0.1", - "downloadUrl": "https://cdn.example.com/bundles/home_1.0.1.bundle", - "md5": "a1b2c3d4...", - "size": 204800 -} -``` - ---- - -### 下载 Bundle - -`downloadUrl` 返回的 URL 可直接 `GET` 下载，响应体为 bundle 二进制内容。 - ---- - -## 租户服务（/api/） - -### 创建应用（租户管理后台调用） - -``` -POST /api/apps -Authorization: Bearer -Content-Type: application/json - -{ "name": "我的 App", "platform": "ANDROID" } -``` - ---- - ## 数据模型 ### ImMessage diff --git a/docs-site/docs/server/errors.md b/docs-site/docs/server/errors.md index e928a5b..5204780 100644 --- a/docs-site/docs/server/errors.md +++ b/docs-site/docs/server/errors.md @@ -37,7 +37,7 @@ --- -## WebSocket 错误码 +## IM 连接错误码 | 关闭码 | 说明 | 处理建议 | |--------|------|----------| @@ -56,7 +56,7 @@ | 错误 | 说明 | |------|------| | `XuqmSDK not initialized. Call XuqmSDK.initialize() first.` | 未调用初始化 | -| `WebSocket not connected` | 发送消息时未连接 | +| `IM not connected` | 发送消息时未连接 | | `edit message failed` | 编辑消息接口返回空 | | `revoke message failed` | 撤回消息接口返回空 | @@ -71,22 +71,22 @@ | 错误 | 说明 | |------|------| | `XuqmSDK not initialized. Call init() first.` | 未调用初始化 | -| `WebSocket not connected` | WebSocket 未连接时发送消息 | +| `IM not connected` | IM 未连接时发送消息 | | `IM token is empty` | 未登录或 Token 已清空 | --- ## 常见错误排查 -### Q: 登录后 WebSocket 无法连接 +### Q: 登录后 IM 无法连接 - 检查 `userSig` 是否有效（未过期、签名正确） -- 检查网络是否允许 WebSocket（防火墙、代理） -- 检查 WebSocket 地址是否正确 +- 检查网络是否允许长连接（防火墙、代理） +- 检查 IM 连接地址是否正确 ### Q: 发送消息返回 FAILED -- 检查 WebSocket 连接状态 +- 检查 IM 连接状态 - 检查 `toId` 是否有效 - 检查 `appKey` 是否正确配置 @@ -102,4 +102,4 @@ - 检查 Token 是否在有效期内 - 检查 HTTP Header 中 `Authorization: Bearer {token}` 格式 -[→ Server API 文档 →](./api) +[→ Server API 文档 →](/server/api) diff --git a/docs-site/docs/server/go-sdk.md b/docs-site/docs/server/go-sdk.md new file mode 100644 index 0000000..492fd82 --- /dev/null +++ b/docs-site/docs/server/go-sdk.md @@ -0,0 +1,116 @@ +# Go Server SDK + +XuqmGroup 服务端 Go SDK，提供 IM 消息发送、群管理、Push 推送等能力。 + +--- + +## 安装 + +```bash +go get xuqinmin.com/xuqinmin12/XuqmGroup-ServerSDK-Go +``` + +--- + +## 初始化 + +```go +import xuqmsdk "xuqinmin.com/xuqinmin12/XuqmGroup-ServerSDK-Go" + +client := xuqmsdk.NewClient(xuqmsdk.Config{ + BaseURL: "https://dev.xuqinmin.com", + AppID: "your_app_id", + AppSecret: "your_app_secret", +}) +``` + +> 服务端 SDK 需要 `appSecret` 用于 HMAC 签名，`appSecret` 绝不下发到客户端。 + +--- + +## 发送消息 + +```go +msg, err := client.SendMessage(xuqmsdk.SendMessageRequest{ + ToID: "user_002", + ChatType: "SINGLE", + MsgType: "TEXT", + Content: "Hello from Go SDK!", +}) +if err != nil { + log.Fatal(err) +} +log.Printf("消息已发送: %s", msg.ID) +``` + +### 发送群消息 + +```go +msg, err := client.SendMessage(xuqmsdk.SendMessageRequest{ + ToID: "group_xxx", + ChatType: "GROUP", + MsgType: "TEXT", + Content: "大家好", +}) +``` + +### 撤回消息 + +```go +err := client.RevokeMessage("message_id") +``` + +--- + +## 群管理 + +```go +// 创建群组 +group, err := client.CreateGroup(xuqmsdk.CreateGroupRequest{ + Name: "项目讨论", + MemberIDs: []string{"user_001", "user_002"}, +}) + +// 添加群成员 +err = client.AddGroupMember("group_xxx", "user_003") + +// 移除群成员 +err = client.RemoveGroupMember("group_xxx", "user_003") + +// 获取群列表 +groups, err := client.ListGroups() + +// 获取群成员 +members, err := client.ListGroupMembers("group_xxx") +``` + +--- + +## Push 推送 + +```go +err := client.SendPush(xuqmsdk.SendPushRequest{ + UserID: "user_001", + Title: "新消息", + Body: "你有一条未读消息", + Payload: map[string]string{"chatId": "user_002"}, +}) +``` + +--- + +## 错误处理 + +SDK 返回的错误实现了标准 `error` 接口。业务方可根据错误类型做不同处理： + +```go +msg, err := client.SendMessage(req) +if err != nil { + // 可断言为 *xuqmsdk.APIError 获取 HTTP 状态码和详细错误信息 + if apiErr, ok := err.(*xuqmsdk.APIError); ok { + log.Printf("API 错误: status=%d, code=%d, message=%s", apiErr.Status, apiErr.Code, apiErr.Message) + } +} +``` + +[→ Server API 文档 →](/server/api) diff --git a/docs-site/docs/server/python-sdk.md b/docs-site/docs/server/python-sdk.md new file mode 100644 index 0000000..fb3cd06 --- /dev/null +++ b/docs-site/docs/server/python-sdk.md @@ -0,0 +1,112 @@ +# Python Server SDK + +XuqmGroup 服务端 Python SDK，提供 IM 消息发送、群管理、Push 推送等能力。 + +--- + +## 安装 + +```bash +pip install xuqm-im-server-sdk +``` + +--- + +## 初始化 + +```python +from xuqm_im_server_sdk import XuqmImServerSdk + +sdk = XuqmImServerSdk( + base_url="https://dev.xuqinmin.com", + app_id="your_app_id", + app_secret="your_app_secret", +) +``` + +> 服务端 SDK 需要 `app_secret` 用于 HMAC 签名，`app_secret` 绝不下发到客户端。 + +--- + +## 发送消息 + +```python +msg = sdk.send_message( + to_id="user_002", + chat_type="SINGLE", + msg_type="TEXT", + content="Hello from Python SDK!", +) +print(f"消息已发送: {msg['id']}") +``` + +### 发送群消息 + +```python +msg = sdk.send_message( + to_id="group_xxx", + chat_type="GROUP", + msg_type="TEXT", + content="大家好", +) +``` + +### 撤回消息 + +```python +sdk.revoke_message("message_id") +``` + +--- + +## 群管理 + +```python +# 创建群组 +group = sdk.create_group( + name="项目讨论", + member_ids=["user_001", "user_002"], +) + +# 添加群成员 +sdk.add_group_member("group_xxx", "user_003") + +# 移除群成员 +sdk.remove_group_member("group_xxx", "user_003") + +# 获取群列表 +groups = sdk.list_groups() + +# 获取群成员 +members = sdk.list_group_members("group_xxx") +``` + +--- + +## Push 推送 + +```python +sdk.send_push( + user_id="user_001", + title="新消息", + body="你有一条未读消息", + payload={"chatId": "user_002"}, +) +``` + +--- + +## 错误处理 + +SDK 在请求失败时会抛出 `XuqmAPIError` 异常： + +```python +from xuqm_im_server_sdk import XuqmAPIError + +try: + msg = sdk.send_message(to_id="user_002", chat_type="SINGLE", msg_type="TEXT", content="Hello") +except XuqmAPIError as e: + print(f"API 错误: status={e.status}, code={e.code}, message={e.message}") +``` + +[→ Server API 文档 →](/server/api) diff --git a/docs-site/docs/vue3/im.md b/docs-site/docs/vue3/im.md index 03b964d..33e63b3 100644 --- a/docs-site/docs/vue3/im.md +++ b/docs-site/docs/vue3/im.md @@ -1,6 +1,6 @@ # Vue3 IM 接入 -基于 `@xuqm/vue3-sdk` 实现即时通讯功能，支持原生 WebSocket + STOMP 协议。 +基于 `@xuqm/vue3-sdk` 实现即时通讯功能。 --- @@ -13,7 +13,6 @@ import { init } from '@xuqm/vue3-sdk' init({ appKey: 'your_app_key', - appSecret: 'your_app_secret', }) ``` @@ -222,5 +221,3 @@ await removeFriend('user_002') | `MERGE` | 合并转发 | | `FORWARD` | 转发 | | `REVOKED` | 撤回 | - -[→ 完整 API Reference](./api) diff --git a/docs-site/docs/vue3/index.md b/docs-site/docs/vue3/index.md index afd83f0..217a0b3 100644 --- a/docs-site/docs/vue3/index.md +++ b/docs-site/docs/vue3/index.md @@ -8,7 +8,6 @@ |------|------| | `useXuqm()` | 全局初始化 Composable | | `useIm()` | IM 单聊/群聊响应式状态 | -| `useUpdate()` | 版本检查与热更新 | | `XuqmProvider` | 可选根组件（自动初始化）| ## 安装 @@ -100,17 +99,6 @@ subscribeGroup(group.id) await sendMessage(group.id, 'GROUP', 'TEXT', '大家好') ``` -### 6. 检查 App/RN 更新 - -```ts -import { useUpdate } from '@xuqm/vue3-sdk' - -const { checkAppUpdate, checkRNUpdate } = useUpdate() - -const appInfo = await checkAppUpdate(1) // 当前 versionCode -const rnBundle = await checkRNUpdate('home', '1.0.0') -``` - ## 响应式状态 `useIm()` 返回的响应式 ref： @@ -119,7 +107,7 @@ const rnBundle = await checkRNUpdate('home', '1.0.0') const { messages, // Ref 单聊消息列表 groupMessages, // Ref 当前群消息列表 - connected, // Ref WS 连接状态 + connected, // Ref IM 连接状态 currentUser, // Ref 当前登录用户 } = useIm() ``` diff --git a/docs-site/docs/vue3/setup.md b/docs-site/docs/vue3/setup.md index 9bddb85..36d44be 100644 --- a/docs-site/docs/vue3/setup.md +++ b/docs-site/docs/vue3/setup.md @@ -64,10 +64,8 @@ import { init } from '@xuqm/vue3-sdk' init({ appKey: 'your_app_key', - appSecret: 'your_app_secret', debug: true, // 可选 baseUrl: 'https://...', // 可选，默认 https://dev.xuqinmin.com - wsUrl: 'wss://.../ws/im', // 可选，默认 wss://dev.xuqinmin.com/ws/im }) ```