From 8fb59bb5f226e11608675a6eabe40e856c0016b7 Mon Sep 17 00:00:00 2001
From: XuqmGroup <noreply@xuqm.com>
Date: Mon, 15 Jun 2026 10:37:57 +0800
Subject: [PATCH] =?UTF-8?q?fix(common):=20platformUrl=20=E5=8F=AF=E9=80=89?=
 =?UTF-8?q?=EF=BC=8C=E4=B8=8D=E4=BC=A0=E4=BD=BF=E7=94=A8=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E5=85=AC=E6=9C=89=E5=B9=B3=E5=8F=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

XuqmInitOptions.platformUrl 改为可选字段。
initialize() 内部：platformUrl ?? DEFAULT_TENANT_PLATFORM_URL。
公有云用户无需传 platformUrl，私有化部署传自有平台地址。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/SDK设计规范.md           | 52 +++++++++++++++++------------------
 packages/common/src/config.ts |  1 +
 packages/common/src/sdk.ts    |  3 +-
 3 files changed, 29 insertions(+), 27 deletions(-)

diff --git a/docs/SDK设计规范.md b/docs/SDK设计规范.md
index 43d35d8..aa859e2 100644
--- a/docs/SDK设计规范.md
+++ b/docs/SDK设计规范.md
@@ -42,16 +42,29 @@ SDK 读取配置文件后，自动调用 **方式 B** 完成完整初始化（
 App 主动调用，适用于无法提前写入配置文件或需要动态切换环境的场景。
 
 ```ts
-await XuqmSDK.initialize({
-  appKey: 'your-app-key',
-  platformUrl: 'https://www.51szyx.com',  // 平台地址，必填
-  debug: __DEV__,
-})
+// 使用默认公有平台（www.51szyx.com）
+await XuqmSDK.initialize({ appKey: 'your-app-key', debug: __DEV__ })
+
+// 使用私有化部署平台
+await XuqmSDK.initialize({ appKey: 'your-app-key', platformUrl: 'https://your-server.com' })
+```
+
+**签名**：
+
+```ts
+interface XuqmInitOptions {
+  appKey: string
+  platformUrl?: string  // 平台地址，可选；不传则使用内置默认公有平台地址
+  debug?: boolean
+}
+
+XuqmSDK.initialize(options: XuqmInitOptions): Promise<void>
 ```
 
 **行为**：
-1. 请求 `{platformUrl}/api/sdk/config?appKey={appKey}`
-2. 平台根据 appKey 和租户服务开通情况，返回该 App 专属的服务配置：
+1. `platformUrl` 未传时使用内置默认公有平台地址（`DEFAULT_TENANT_PLATFORM_URL`）
+2. 请求 `{platformUrl}/api/sdk/config?appKey={appKey}`
+3. 平台根据 appKey 和租户服务开通情况，返回该 App 专属的服务配置：
    ```json
    {
      "apiUrl": "...",         // 通用 API 地址
@@ -62,20 +75,8 @@ await XuqmSDK.initialize({
      "imEnabled": true        // 是否开通 IM 服务
    }
    ```
-3. SDK 将服务配置保存，供所有子 SDK 使用。
-4. **失败时直接抛出错误**，不降级，不回退到默认地址。调用方必须处理异常。
-
-**签名**：
-
-```ts
-interface XuqmInitOptions {
-  appKey: string
-  platformUrl: string        // 平台地址，必填
-  debug?: boolean
-}
-
-XuqmSDK.initialize(options: XuqmInitOptions): Promise<void>
-```
+4. SDK 将服务配置保存，供所有子 SDK 使用。
+5. **失败时直接抛出错误**，不降级。调用方必须处理异常。
 
 ---
 
@@ -471,11 +472,10 @@ App
 
 ```ts
 // 1. 初始化（通常在 App 入口，配置文件模式下可省略）
-await XuqmSDK.initialize({
-  appKey: 'your-app-key',
-  platformUrl: 'https://www.51szyx.com',
-  debug: __DEV__,
-})
+// 公有平台：不传 platformUrl
+await XuqmSDK.initialize({ appKey: 'your-app-key', debug: __DEV__ })
+// 私有化部署：传入自有平台地址
+// await XuqmSDK.initialize({ appKey: 'your-app-key', platformUrl: 'https://your-server.com' })
 
 // 2. 业务登录（App 自有登录逻辑）
 const result = await api.login(phone, verifyCode)
diff --git a/packages/common/src/config.ts b/packages/common/src/config.ts
index f282717..3229603 100644
--- a/packages/common/src/config.ts
+++ b/packages/common/src/config.ts
@@ -1,5 +1,6 @@
 export interface XuqmInitOptions {
   appKey: string
+  platformUrl?: string  // 不传则使用内置默认公有平台地址
   debug?: boolean
 }
 
diff --git a/packages/common/src/sdk.ts b/packages/common/src/sdk.ts
index 544dbc5..04dfae8 100644
--- a/packages/common/src/sdk.ts
+++ b/packages/common/src/sdk.ts
@@ -42,7 +42,8 @@ export const XuqmSDK = {
   async initialize(options: XuqmInitOptions): Promise<void> {
     if (isInitialized()) return
     ensureInitPromise()
-    const configUrl = `${DEFAULT_TENANT_PLATFORM_URL}/api/sdk/config?appKey=${options.appKey}`
+    const baseUrl = options.platformUrl ?? DEFAULT_TENANT_PLATFORM_URL
+    const configUrl = `${baseUrl}/api/sdk/config?appKey=${options.appKey}`
     try {
       const res = await fetch(configUrl)
       const json = await res.json()