From e912a5e65e63f341cfaa5bf130ae3f949dd945fc Mon Sep 17 00:00:00 2001 From: XuqmGroup Date: Sat, 16 May 2026 11:56:40 +0800 Subject: [PATCH] docs: remove WebSocket doc, strip Update from server SDKs, add Harmony license MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove docs/server/websocket.md and sidebar entry - Server API: remove Update 服务 section (only IM + Push) - Go/Python/Java SDK docs: remove Update from intro and capability tables - RN license: remove manual initialize(baseUrl) section - Flutter license: remove manual initialize(baseUrl) section - Flutter/Harmony: fix git URLs to xuqmGroup org - Harmony: add LicenseSDK to modules table and create harmony/license.md Co-Authored-By: Claude Sonnet 4.6 --- docs-site/docs/.vitepress/config.ts | 2 +- docs-site/docs/flutter/license.md | 10 +- docs-site/docs/flutter/setup.md | 2 +- docs-site/docs/harmony/index.md | 2 + docs-site/docs/harmony/license.md | 166 ++++++++++++++++++++++++ docs-site/docs/harmony/setup.md | 1 + docs-site/docs/rn/license.md | 22 +--- docs-site/docs/server/api.md | 59 +-------- docs-site/docs/server/go-sdk.md | 6 +- docs-site/docs/server/java-sdk.md | 6 +- docs-site/docs/server/python-sdk.md | 6 +- docs-site/docs/server/websocket.md | 192 ---------------------------- 12 files changed, 181 insertions(+), 293 deletions(-) create mode 100644 docs-site/docs/harmony/license.md delete mode 100644 docs-site/docs/server/websocket.md diff --git a/docs-site/docs/.vitepress/config.ts b/docs-site/docs/.vitepress/config.ts index a165558..31652d5 100644 --- a/docs-site/docs/.vitepress/config.ts +++ b/docs-site/docs/.vitepress/config.ts @@ -84,6 +84,7 @@ export default defineConfig({ { text: 'IM 接入', link: '/harmony/im' }, { text: '推送接入', link: '/harmony/#push-接入' }, { text: '版本管理', link: '/harmony/#update-接入' }, + { text: '授权管理', link: '/harmony/license' }, ], '/miniprogram/': [ { text: '概览', link: '/miniprogram/' }, @@ -100,7 +101,6 @@ export default defineConfig({ { text: 'Go Server SDK', link: '/server/go-sdk' }, { text: 'Java Server SDK', link: '/server/java-sdk' }, { text: 'Python Server SDK', link: '/server/python-sdk' }, - { text: 'WebSocket 协议', link: '/server/websocket' }, { text: '错误码', link: '/server/errors' }, ], }, diff --git a/docs-site/docs/flutter/license.md b/docs-site/docs/flutter/license.md index cf0a7f3..d0891b1 100644 --- a/docs-site/docs/flutter/license.md +++ b/docs-site/docs/flutter/license.md @@ -12,7 +12,7 @@ dependencies: xuqm_flutter_license: git: - url: https://xuqinmin.com/xuqinmin12/XuqmGroup-FlutterSDK.git + url: https://xuqinmin.com/xuqmGroup/XuqmGroup-FlutterSDK.git ref: v0.2.2 path: packages/license ``` @@ -74,14 +74,6 @@ final result = await checkLicense( ## 5. API 说明 -### initialize - -```dart -void initialize(String appKey, {String? baseUrl, String? deviceName}) -``` - -手动初始化，适用于不使用 License 文件的场景。 - ### initializeFromFile ```dart diff --git a/docs-site/docs/flutter/setup.md b/docs-site/docs/flutter/setup.md index bc4d17b..75dcee8 100644 --- a/docs-site/docs/flutter/setup.md +++ b/docs-site/docs/flutter/setup.md @@ -12,7 +12,7 @@ SDK 通过 Gitea Git 仓库发布，在 `pubspec.yaml` 中配置： dependencies: xuqm_flutter_sdk: git: - url: https://xuqinmin.com/xuqinmin12/XuqmGroup-FlutterSDK.git + url: https://xuqinmin.com/xuqmGroup/XuqmGroup-FlutterSDK.git ref: v0.2.2 ``` diff --git a/docs-site/docs/harmony/index.md b/docs-site/docs/harmony/index.md index 2e5127a..cf32498 100644 --- a/docs-site/docs/harmony/index.md +++ b/docs-site/docs/harmony/index.md @@ -8,7 +8,9 @@ |------|------| | `XuqmSDK` | 全局初始化 | | `ImSDK` | 单聊、群聊、消息收发 | +| `PushSDK` | Push Token 注册与注销 | | `UpdateSDK` | App 版本检查、整包更新 | +| `LicenseSDK` | 设备授权注册与验证 | ## 安装 diff --git a/docs-site/docs/harmony/license.md b/docs-site/docs/harmony/license.md new file mode 100644 index 0000000..a79ebe4 --- /dev/null +++ b/docs-site/docs/harmony/license.md @@ -0,0 +1,166 @@ +# HarmonyOS 授权管理（License SDK） + +**模块**：`LicenseSDK` · **包名**：`@xuqm/harmony-sdk` + +--- + +## 1. 安装 + +`LicenseSDK` 已包含在 `@xuqm/harmony-sdk` 中，无需额外安装。确保 `oh-package.json5` 中已依赖： + +```json5 +{ + "dependencies": { + "@xuqm/harmony-sdk": "^0.1.0" + } +} +``` + +执行： + +```bash +ohpm install +``` + +--- + +## 2. 放置 License 文件 + +从租户平台下载 `.xuqmlicense` 加密文件，放入项目 `resources/rawfile/` 目录： + +``` +entry/ + src/main/ + resources/ + rawfile/ + license.xuqm +``` + +--- + +## 3. 初始化并检查授权 + +在 `EntryAbility.onCreate` 或应用启动入口中初始化 License： + +```typescript +import { LicenseSDK } from '@xuqm/harmony-sdk' +import common from '@ohos.app.ability.common' +import rawfileManager from '@ohos.rawfileManager' + +export default class EntryAbility extends UIAbility { + async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { + // 读取 License 文件内容 + const context = getContext(this) as common.UIAbilityContext + const content = await readRawFile(context, 'license.xuqm') + + // 从加密文件初始化 + await LicenseSDK.initializeFromFile(content) + + // 检查授权 + const result = await LicenseSDK.checkLicense() + if (result.type === 'success') { + console.log('授权通过:', result.reason) + } else { + console.warn('授权失败:', result.message) + } + } +} + +async function readRawFile(context: common.UIAbilityContext, filename: string): Promise { + const rm = context.resourceManager + const data = await rm.getRawFileContent(filename) + return new TextDecoder().decode(data) +} +``` + +--- + +## 4. 携带用户信息 + +```typescript +import { LicenseSDK, LicenseUserInfo } from '@xuqm/harmony-sdk' + +const userInfo: LicenseUserInfo = { + userId: 'user_001', + name: '张三', + email: 'zhangsan@company.com', +} + +const result = await LicenseSDK.checkLicense(userInfo) +``` + +--- + +## 5. API 说明 + +### initializeFromFile + +```typescript +LicenseSDK.initializeFromFile(encryptedContent: string): Promise +``` + +从加密 License 文件内容自动解析 `appKey` 并初始化。 + +### checkLicense + +```typescript +LicenseSDK.checkLicense(userInfo?: LicenseUserInfo): Promise +``` + +返回 `{ type: 'success', reason: string }` 或 `{ type: 'error', message: string }`。 + +**缓存策略**：10 分钟有效期，有效期内不发起网络请求。 + +### getStatus + +```typescript +LicenseSDK.getStatus(): Promise<'ok' | 'denied' | 'unknown'> +``` + +### getDeviceId + +```typescript +LicenseSDK.getDeviceId(): Promise +``` + +### clear + +```typescript +LicenseSDK.clear(): Promise +``` + +--- + +## 6. 数据存储 + +| 数据 | 存储方式 | +|------|---------| +| deviceId | `preferences`（应用持久化存储）| +| token | `preferences` | +| 授权状态 | `preferences` | +| statusTime | `preferences` | + +--- + +## 7. 离线模式 + +- 首次激活需要网络连接 +- 激活后 10 分钟缓存内可离线使用 +- 网络异常时，若历史缓存成功，继续返回授权通过 + +--- + +## 8. 权限配置 + +使用 License SDK 需要网络权限，确保 `module.json5` 中已声明： + +```json5 +{ + "module": { + "requestPermissions": [ + { "name": "ohos.permission.INTERNET" }, + { "name": "ohos.permission.GET_NETWORK_INFO" } + ] + } +} +``` diff --git a/docs-site/docs/harmony/setup.md b/docs-site/docs/harmony/setup.md index fd53855..ba07bf7 100644 --- a/docs-site/docs/harmony/setup.md +++ b/docs-site/docs/harmony/setup.md @@ -103,3 +103,4 @@ const session = await XuqmSDK.login('user_001', 'your_user_sig_jwt') ## 下一步 - [HarmonyOS IM 接入 →](./im) +- [HarmonyOS 授权管理 →](./license) diff --git a/docs-site/docs/rn/license.md b/docs-site/docs/rn/license.md index 6281c9e..3e8810d 100644 --- a/docs-site/docs/rn/license.md +++ b/docs-site/docs/rn/license.md @@ -20,25 +20,13 @@ cd ios && pod install ## 2. 放置 License 文件 -从租户平台下载 `.xuqmlicense` 加密文件，通过 `react-native-raw-text` 或 `require()` 将其作为文本资源嵌入 App。 - -**方式一：require 字符串资源（推荐）** +从租户平台下载 `.xuqmlicense` 加密文件，通过 `require()` 将其作为文本资源嵌入 App。 ```ts // 将 license.xuqm 放入 src/assets/ const licenseContent = require('./assets/license.xuqm') ``` -**方式二：手动初始化** - -```ts -import { initialize } from '@xuqm/rn-license' - -initialize('your_app_key', { - baseUrl: 'https://auth.dev.xuqinmin.com', -}) -``` - --- ## 3. 检查授权 @@ -79,14 +67,6 @@ const result = await checkLicense(userInfo) ## 5. API 说明 -### initialize - -```ts -initialize(appKey: string, options?: { baseUrl?: string; deviceName?: string }): void -``` - -手动初始化，适用于不使用 License 文件的场景。 - ### initializeFromFile ```ts diff --git a/docs-site/docs/server/api.md b/docs-site/docs/server/api.md index 9faeebb..4f4582a 100644 --- a/docs-site/docs/server/api.md +++ b/docs-site/docs/server/api.md @@ -1,10 +1,9 @@ # Server API 参考 -XuqmGroup 的服务端能力分成三类： +XuqmGroup 的服务端能力分成两类： - `IM 服务`：账号、消息、群组、好友、会话、黑名单、管理端、回调 - `Push 服务`：设备注册、离线推送、诊断、管理端 -- `Update 服务`：应用版本、RN Bundle、应用商店提审、发布配置、操作日志 **Base URL**：`https://dev.xuqinmin.com` @@ -198,60 +197,6 @@ XuqmGroup 的服务端能力分成三类： --- -## Update 服务 - -### 应用版本 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/v1/updates/app/check` | 检查应用更新 | -| `POST` | `/api/v1/updates/app/upload` | 上传应用版本 | -| `GET|POST` | `/api/v1/updates/app/inspect` | 检查上传内容 | -| `POST` | `/api/v1/updates/app/{id}/publish` | 发布应用版本 | -| `POST` | `/api/v1/updates/app/{id}/unpublish` | 取消发布 | -| `POST` | `/api/v1/updates/app/{id}/gray` | 灰度发布 | -| `GET` | `/api/v1/updates/app/list` | 版本列表 | - -### RN Bundle - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/v1/rn/update/check` | 检查 RN 更新 | -| `POST` | `/api/v1/rn/upload` | 上传 RN Bundle | -| `GET|POST` | `/api/v1/rn/inspect` | 检查 RN 上传内容 | -| `GET` | `/api/v1/rn/list` | RN 列表 | -| `POST` | `/api/v1/rn/{id}/publish` | 发布 RN Bundle | -| `POST` | `/api/v1/rn/{id}/unpublish` | 取消发布 RN Bundle | -| `POST` | `/api/v1/rn/{id}/gray` | RN 灰度 | - -### 应用商店提审 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/v1/updates/publish/config` | 获取发布配置 | -| `PUT` | `/api/v1/updates/publish/config` | 更新发布配置 | -| `GET` | `/api/v1/updates/gray/members` | 灰度成员列表 | -| `POST` | `/api/v1/updates/gray/members/sync` | 同步灰度成员 | -| `POST` | `/api/v1/updates/gray/members/import` | 导入灰度成员 | -| `GET` | `/api/v1/updates/store/configs` | 获取应用市场配置 | -| `PUT` | `/api/v1/updates/store/configs/{storeType}` | 更新应用市场配置 | -| `DELETE` | `/api/v1/updates/store/configs/{storeType}` | 删除应用市场配置 | -| `GET` | `/api/v1/updates/store/credentials` | 获取市场凭据摘要 | -| `POST` | `/api/v1/updates/store/app/{versionId}/submit` | 预提交应用市场 | -| `POST` | `/api/v1/updates/store/app/{versionId}/execute-submit` | 执行提审 | -| `POST` | `/api/v1/updates/store/app/{versionId}/review` | 回写审核结果 | - -### 运营日志与文件 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/v1/updates/ops/logs` | 更新操作日志 | -| `GET` | `/api/v1/updates/files/apk/{filename}` | APK 文件访问 | -| `GET` | `/api/v1/rn/files/{appKey}/{platform}/{moduleId}` | RN Bundle 文件访问 | -| `POST` | `/api/v1/updates/unified/upload` | 统一发布包上传 | - ---- - ## 数据模型约定 ### 应用标识 @@ -287,4 +232,4 @@ XuqmGroup 的服务端能力分成三类： - 服务端业务代码统一使用 Java / Go / Python Server SDK 调用上述 REST 接口 - 客户端统一使用 `appKey` 作为应用上下文 - 实时刷新场景建议使用 IM SDK 订阅服务端事件 -- 更新、Push、IM 的后台能力可以独立接入，也可以组合使用 +- Push、IM 的后台能力可以独立接入，也可以组合使用 diff --git a/docs-site/docs/server/go-sdk.md b/docs-site/docs/server/go-sdk.md index 4e210f5..01f1e76 100644 --- a/docs-site/docs/server/go-sdk.md +++ b/docs-site/docs/server/go-sdk.md @@ -1,11 +1,10 @@ # Go Server SDK -XuqmGroup 服务端 Go SDK，按照腾讯云服务端 API 的分类方式封装了： +XuqmGroup 服务端 Go SDK，封装了： - IM 账号、UserSig 生成与登录、消息、群组、好友、会话、黑名单 -- 管理端 Webhook、统计、操作日志 +- 管理端 Webhook、操作日志 - Push 注册与推送 -- Update 版本管理、RN Bundle、应用商店提审 --- @@ -62,7 +61,6 @@ login, err := client.LoginWithUserSig("user_001", userSig) | 管理端 | `QueryUserState`, `KickUsers`, `BatchSendMessage`, `AdminSetMsgRead`, `ImportMessages`, `AdminTransferGroupOwner`, `AdminUpdateGroupAttributes`, `AdminRemoveGroupAttributes`, `AdminGroupReadReceipts` | | Webhook | `ListWebhooks`, `CreateWebhook`, `UpdateWebhook`, `DeleteWebhook`, `VerifyCallbackSignature`, `ParseCallbackEnvelope` | | Push | `RegisterPushToken`, `SendPush`, `PushUserStatus`, `PushDeviceLogs`, `TestOfflinePush` | -| Update | `CheckAppUpdate`, `UploadAppVersion`, `PublishAppVersion`, `UnpublishAppVersion`, `GrayAppVersion`, `ListAppVersions`, `CheckRnUpdate`, `UploadRnBundle`, `PublishRnBundle`, `UnpublishRnBundle`, `ListRnBundles` | --- diff --git a/docs-site/docs/server/java-sdk.md b/docs-site/docs/server/java-sdk.md index 39738a5..9484ee4 100644 --- a/docs-site/docs/server/java-sdk.md +++ b/docs-site/docs/server/java-sdk.md @@ -1,13 +1,12 @@ # Java Server SDK -XuqmGroup 服务端 Java SDK，按腾讯云服务端 API 的思路封装了以下能力： +XuqmGroup 服务端 Java SDK，封装了以下能力： - IM 账号、UserSig 生成与登录 - 消息发送、编辑、撤回、历史查询 - 好友、黑名单、会话、群组 -- Webhook、管理端操作、统计 +- Webhook、管理端操作 - Push 注册与发送 -- Update 版本检查、上传、发布、灰度、应用商店提审 --- @@ -121,7 +120,6 @@ client.revokeMessage("message_id"); | 管理端 | `queryUserState`, `kickUsers`, `batchSendMessage`, `adminSetMsgRead`, `importMessages`, `adminTransferGroupOwner`, `adminUpdateGroupAttributes`, `adminRemoveGroupAttributes`, `adminGroupReadReceipts` | | Webhook | `listWebhooks`, `createWebhook`, `updateWebhook`, `deleteWebhook`, `verifyCallbackSignature`, `parseCallbackEnvelope`, 各类 `parse*CallbackPayload` | | Push | `registerPushToken`, `sendPush`, `pushUserStatus`, `pushDeviceLogs`, `testOfflinePush` | -| Update | `checkAppUpdate`, `uploadAppVersion`, `publishAppVersion`, `unpublishAppVersion`, `grayAppVersion`, `listAppVersions`, `checkRnUpdate`, `uploadRnBundle`, `publishRnBundle`, `unpublishRnBundle`, `listRnBundles` | ## 群管理示例 diff --git a/docs-site/docs/server/python-sdk.md b/docs-site/docs/server/python-sdk.md index 19d6e15..0947ca6 100644 --- a/docs-site/docs/server/python-sdk.md +++ b/docs-site/docs/server/python-sdk.md @@ -1,11 +1,10 @@ # Python Server SDK -XuqmGroup 服务端 Python SDK，按照腾讯云服务端 API 的分类方式封装了： +XuqmGroup 服务端 Python SDK，封装了： - IM 账号、UserSig 生成与登录、消息、群组、好友、会话、黑名单 -- 管理端 Webhook、统计、操作日志 +- 管理端 Webhook、操作日志 - Push 注册与推送 -- Update 版本管理、RN Bundle、应用商店提审 --- @@ -59,7 +58,6 @@ login = sdk.login_with_user_sig("user_001", user_sig) | 管理端 | `query_user_state`, `kick_users`, `batch_send_message`, `admin_set_msg_read`, `import_messages`, `admin_transfer_group_owner`, `admin_update_group_attributes`, `admin_remove_group_attributes`, `admin_group_read_receipts` | | Webhook | `list_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook`, `verify_callback_signature`, `parse_callback_envelope` | | Push | `register_push_token`, `send_push`, `push_user_status`, `push_device_logs`, `test_offline_push` | -| Update | `check_app_update`, `upload_app_version`, `publish_app_version`, `unpublish_app_version`, `gray_app_version`, `list_app_versions`, `check_rn_update`, `upload_rn_bundle`, `publish_rn_bundle`, `unpublish_rn_bundle`, `list_rn_bundles` | --- diff --git a/docs-site/docs/server/websocket.md b/docs-site/docs/server/websocket.md deleted file mode 100644 index 570e910..0000000 --- a/docs-site/docs/server/websocket.md +++ /dev/null @@ -1,192 +0,0 @@ -# WebSocket 协议文档 - -XuqmGroup IM 使用 **STOMP over WebSocket** 协议进行实时消息通信。 - ---- - -## 连接地址 - -| 环境 | 地址 | -|------|------| -| 演示环境 | `wss://dev.xuqinmin.com/ws/im` | -| 生产环境 | 由租户平台分配 | - -连接时需携带 `token` 参数： - -``` -wss://dev.xuqinmin.com/ws/im?token={userSig} -``` - ---- - -## 心跳机制 - -客户端在 STOMP CONNECT 帧中声明心跳： - -``` -CONNECT -accept-version:1.2 -heart-beat:0,0 -host:dev.xuqinmin.com -Authorization:Bearer {token} - -\x00 -``` - -> 当前服务端不强制心跳，客户端可依赖 WebSocket 原生 `onclose`/`onerror` 检测断线。 - ---- - -## 消息格式（STOMP） - -### CONNECT 帧 - -客户端建立 WebSocket 连接后，发送 STOMP CONNECT： - -``` -CONNECT -accept-version:1.2 -heart-beat:0,0 -host:dev.xuqinmin.com -Authorization:Bearer {token} - -\x00 -``` - -### CONNECTED 帧 - -服务端鉴权通过后返回： - -``` -CONNECTED -version:1.2 - -\x00 -``` - -### SUBSCRIBE 帧 - -订阅个人消息队列（自动执行）： - -``` -SUBSCRIBE -id:sub-1 -destination:/user/queue/messages - -\x00 -``` - -订阅群消息： - -``` -SUBSCRIBE -id:sub-2 -destination:/topic/group/{groupId} - -\x00 -``` - -### SEND 帧 — 发送消息 - -``` -SEND -destination:/app/chat.send -content-type:application/json - -{"appKey":"ak_demo_chat","messageId":"...","toId":"user_002","chatType":"SINGLE","msgType":"TEXT","content":"Hello"} -\x00 -``` - -### SEND 帧 — 撤回消息 - -``` -SEND -destination:/app/chat.revoke -content-type:application/json - -{"appKey":"ak_demo_chat","messageId":"..."} -\x00 -``` - -### SEND 帧 — 同步离线消息 - -``` -SEND -destination:/app/chat.sync -content-type:application/json - -{"appKey":"ak_demo_chat"} -\x00 -``` - -### MESSAGE 帧 — 接收消息 - -``` -MESSAGE -destination:/user/queue/messages -message-id:... - -{"id":"...","fromId":"user_002","toId":"user_001","chatType":"SINGLE","msgType":"TEXT","content":"Hello","status":"SENT","createdAt":1715000000000} -\x00 -``` - -### ERROR 帧 - -``` -ERROR -message:Unauthorized - -Unauthorized -\x00 -``` - ---- - -## 订阅路径 - -| 路径 | 说明 | -|------|------| -| `/user/queue/messages` | 个人消息队列（登录后自动订阅）| -| `/topic/group/{groupId}` | 群消息频道 | - ---- - -## 服务端配置 - -基于 Spring WebSocket + STOMP： - -```java -@Configuration -@EnableWebSocketMessageBroker -public class WebSocketConfig implements WebSocketMessageBrokerConfigurer { - @Override - public void configureMessageBroker(MessageBrokerRegistry registry) { - registry.enableSimpleBroker("/topic", "/queue"); - registry.setApplicationDestinationPrefixes("/app"); - registry.setUserDestinationPrefix("/user"); - } - - @Override - public void registerStompEndpoints(StompEndpointRegistry registry) { - registry.addEndpoint("/ws/im") - .setAllowedOriginPatterns("*") - .withSockJS(); - registry.addEndpoint("/ws/im") - .setAllowedOriginPatterns("*"); - } -} -``` - ---- - -## 自定义客户端接入 - -如果业务方不使用官方 SDK，可按以下流程自建客户端： - -1. 通过 `wss://host/ws/im?token=xxx` 建立 WebSocket -2. 发送 STOMP CONNECT 帧（携带 `Authorization: Bearer {token}`） -3. 收到 CONNECTED 后，订阅 `/user/queue/messages` -4. 发送消息时构造 STOMP SEND 帧，`destination: /app/chat.send` -5. 收到服务端 MESSAGE 帧后解析 JSON body - -[→ Server API 文档 →](./api)