升级 SGS Map SDK 至 2.5.0

2026-07-16 09:43:52 +08:00
parent 6db0b71562
commit 72885b7f54
23 changed files with 1274 additions and 61 deletions
--- a/.agents/skills/shenzhen-natural-museum-dev/SKILL.md
+++ b/.agents/skills/shenzhen-natural-museum-dev/SKILL.md
@@ -452,7 +452,7 @@ pnpm build:h5
 - Audio fallback URLs such as `example.com` are not valid explain capability.
 - `src/pages/route/detail.vue` may still contain historical navigation states such as planning/navigating/arrived/location-error. Keep them blocked unless real graph data exists.
 - Runtime static JSON loading through `uni.request` must be verified on H5 for current work; verify mp-weixin only when explicitly requested.
- SGS Map SDK H5 integration depends on the sibling project `E:\MyWork\深圳国际艺术馆\智慧导览\smart-navigation-system`, especially `sgs-frontend-map/sdk-src`, `public/sdk/sgs-map-sdk.min.js`, and `/h5-sdk`.
+- SGS Map SDK H5 integration depends on the sibling project `E:\MyWork\深圳国际艺术馆\智慧导览\smart-navigation-system`, especially `sgs-frontend-map/sdk-src`, `public/sdk/sgs-map-sdk.min.js`, and the independently deployed `/engine/index.html`. Treat an SPA fallback HTTP 200 as unhealthy; validate Engine title/assets and `HELLO` -> `ENGINE_READY`.
 - SGS Map SDK uses iframe + `postMessage`; target origin, iframe lifecycle, and event bridge errors are separate operational risks from local Three.js rendering.
 - SDK mode should not be treated as proof of certified indoor navigation unless route graph/nav data and runtime route behavior are verified.
 - Mixing static nav-assets POI IDs with backend SGS Map POI IDs can break search, focus, explain location previews, and route actions unless adapters normalize stable IDs deliberately.
--- a/.claude/skills/shenzhen-natural-museum-dev/SKILL.md
+++ b/.claude/skills/shenzhen-natural-museum-dev/SKILL.md
@@ -452,7 +452,7 @@ pnpm build:h5
 - Audio fallback URLs such as `example.com` are not valid explain capability.
 - `src/pages/route/detail.vue` may still contain historical navigation states such as planning/navigating/arrived/location-error. Keep them blocked unless real graph data exists.
 - Runtime static JSON loading through `uni.request` must be verified on H5 for current work; verify mp-weixin only when explicitly requested.
- SGS Map SDK H5 integration depends on the sibling project `E:\MyWork\深圳国际艺术馆\智慧导览\smart-navigation-system`, especially `sgs-frontend-map/sdk-src`, `public/sdk/sgs-map-sdk.min.js`, and `/h5-sdk`.
+- SGS Map SDK H5 integration depends on the sibling project `E:\MyWork\深圳国际艺术馆\智慧导览\smart-navigation-system`, especially `sgs-frontend-map/sdk-src`, `public/sdk/sgs-map-sdk.min.js`, and the independently deployed `/engine/index.html`. Treat an SPA fallback HTTP 200 as unhealthy; validate Engine title/assets and `HELLO` -> `ENGINE_READY`.
 - SGS Map SDK uses iframe + `postMessage`; target origin, iframe lifecycle, and event bridge errors are separate operational risks from local Three.js rendering.
 - SDK mode should not be treated as proof of certified indoor navigation unless route graph/nav data and runtime route behavior are verified.
 - Mixing static nav-assets POI IDs with backend SGS Map POI IDs can break search, focus, explain location previews, and route actions unless adapters normalize stable IDs deliberately.
--- a/.env.development
+++ b/.env.development
@@ -15,8 +15,8 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
-VITE_SGS_H5_ENGINE_URL=/h5-sdk
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.5.0
+VITE_SGS_H5_ENGINE_URL=/engine/index.html
 VITE_SGS_SDK_ORIGIN=
 VITE_SGS_SDK_TIMEOUT_MS=15000
 VITE_TENCENT_MAP_KEY=__REPLACE_WITH_TENCENT_MAP_WEB_KEY__
@@ -25,7 +25,7 @@ VITE_PUBLIC_LEGACY_AUDIO_HOST=

 # Vite 开发服务器代理目标，只由 vite.config.ts 读取。
 DEV_PROXY_APP_API_TARGET=http://localhost:3001
-DEV_PROXY_H5_SDK_TARGET=http://localhost:3001
+DEV_PROXY_ENGINE_TARGET=http://localhost:3001
 DEV_PROXY_SDK_TARGET=http://localhost:3001
 DEV_PROXY_MUSEUM_ASSETS_TARGET=http://1.92.206.90:9000
 DEV_PROXY_MINIO_TARGET=http://localhost:3001
--- a/.env.example
+++ b/.env.example
@@ -14,8 +14,8 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
-VITE_SGS_H5_ENGINE_URL=/h5-sdk
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.5.0
+VITE_SGS_H5_ENGINE_URL=/engine/index.html
 VITE_SGS_SDK_ORIGIN=
 VITE_SGS_SDK_TIMEOUT_MS=15000
 VITE_TENCENT_MAP_KEY=__REPLACE_WITH_TENCENT_MAP_WEB_KEY__
@@ -24,7 +24,7 @@ VITE_PUBLIC_LEGACY_AUDIO_HOST=

 # 仅开发环境使用的 Vite 代理目标，只由 vite.config.ts 读取。
 DEV_PROXY_APP_API_TARGET=http://localhost:3001
-DEV_PROXY_H5_SDK_TARGET=http://localhost:3001
+DEV_PROXY_ENGINE_TARGET=http://localhost:3001
 DEV_PROXY_SDK_TARGET=http://localhost:3001
 DEV_PROXY_MUSEUM_ASSETS_TARGET=http://1.92.206.90:9000
 DEV_PROXY_MINIO_TARGET=http://localhost:3001
--- a/.env.production
+++ b/.env.production
@@ -14,8 +14,8 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
-VITE_SGS_H5_ENGINE_URL=/h5-sdk
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.5.0
+VITE_SGS_H5_ENGINE_URL=/engine/index.html
 VITE_SGS_SDK_ORIGIN=https://guide.sznhmuseum.org.cn
 VITE_SGS_SDK_TIMEOUT_MS=15000
 VITE_TENCENT_MAP_KEY=__REPLACE_WITH_TENCENT_MAP_WEB_KEY__
--- a/.env.test
+++ b/.env.test
@@ -14,8 +14,8 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
-VITE_SGS_H5_ENGINE_URL=/h5-sdk
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.5.0
+VITE_SGS_H5_ENGINE_URL=/engine/index.html
 VITE_SGS_SDK_ORIGIN=https://guide.whaoyue.com
 VITE_SGS_SDK_TIMEOUT_MS=30000
 VITE_TENCENT_MAP_KEY=__REPLACE_WITH_TENCENT_MAP_WEB_KEY__
--- a/README.md
+++ b/README.md
@@ -129,8 +129,8 @@ VITE_AUDIO_LANGUAGE=zh-CN

 # SGS SDK/H5 地图基座配置；当前代码尚未把 SDK renderer 接入页面渲染
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
-VITE_SGS_H5_ENGINE_URL=/h5-sdk
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.5.0
+VITE_SGS_H5_ENGINE_URL=/engine/index.html
 VITE_SGS_SDK_ORIGIN=
 VITE_SGS_SDK_TIMEOUT_MS=5000
 ```
@@ -177,7 +177,7 @@ uni build -p h5 && node scripts/copy-h5-nav-assets.cjs
 - `dist/build/h5` 存在应用产物。
 - H5 可访问 `static/nav-assets/...` 下的 GLB/GLTF/bin/texture/manifest 文件。
 - H5 可访问 `static/guide-data` 下的讲解和内容数据。
- 如启用 `api` 或 `sdk` 模式，Nginx/网关需代理 `/app-api`、`/yudao-server`、`/h5-sdk` 等路径。
+- 如启用 `api` 或 `sdk` 模式，Nginx/网关需代理 `/app-api`、`/yudao-server`、`/engine` 等路径。`/engine/index.html` 必须是 SGS Map SDK Engine 2.5.x 的独立发布页面，且其资源路径可加载并能完成 `HELLO` -> `ENGINE_READY`；业务 SPA fallback 返回的 200 不是 Engine 健康。

 更完整的部署说明见 `docs/H5_DEPLOYMENT_GUIDE.md`。

--- a/docs/Data/SGS_SDK_DATA_LAYER_INTEGRATION_GUIDE.md
+++ b/docs/Data/SGS_SDK_DATA_LAYER_INTEGRATION_GUIDE.md
@@ -11,7 +11,7 @@ SGS Map SDK 接入分为两条边界：
 | 边界 | 职责 | 允许接触 SDK/后端字段的位置 | 禁止事项 |
 | --- | --- | --- | --- |
 | 数据层 | 拉取楼层、POI、空间面、导航目的地、诊断信息，并转换为 `MuseumFloor`、`MuseumPoi`、`GuideLocationPreview` 等领域模型 | `src/data/providers`、`src/data/adapters`、`src/repositories` | 页面和组件直接请求 `/app-api/gis/sdk/*` |
-| 渲染层 | 加载 SGS H5 地图基座、管理 iframe/SDK 生命周期、执行切楼层和聚焦命令 | `src/services/sgs`、`src/components/map/SgsMapRenderer.vue` | 把后端数据解析逻辑写进 `SgsMapRenderer.vue` |
+| 渲染层 | 加载 SGS H5 Engine、管理 iframe/SDK 生命周期、执行切楼层和聚焦命令 | `src/services/sgs`、未来独立 renderer | 把后端数据解析逻辑写进 renderer |

 展示层必须只通过以下入口拿数据：

@@ -34,7 +34,7 @@ SGS Map SDK 接入分为两条边界：
 | --- | --- | --- |
 | 后端直连 | `http://1.92.206.90:48080/yudao-server/app-api` | 当前开发机访问超时，需服务端排查防火墙/安全组/监听地址 |
 | 前端代理 | `http://1.92.206.90:3001/app-api` | 可访问，返回后端 `CommonResult code=0` |
-| H5 SDK 基座 | `http://1.92.206.90:3001/h5-sdk` | 可访问 |
+| H5 SDK Engine | `http://1.92.206.90:3001/engine/index.html` | 需部署并按 `HELLO` -> `ENGINE_READY` 验证，HTTP 200 不足以证明健康 |
 | SDK 脚本 | `http://1.92.206.90:3001/sdk/sgs-map-sdk.min.js` | 可访问 |

 本项目推荐环境变量：
@@ -43,7 +43,7 @@ SGS Map SDK 接入分为两条边界：
 VITE_DATA_SOURCE_MODE=sdk
 VITE_API_BASE_URL=/app-api
 VITE_SGS_SDK_SCRIPT_URL=/sdk/sgs-map-sdk.min.js
-VITE_SGS_H5_ENGINE_URL=/h5-sdk
+VITE_SGS_H5_ENGINE_URL=/engine/index.html
 VITE_SGS_SDK_ORIGIN=http://1.92.206.90:3001
 VITE_SGS_SDK_TIMEOUT_MS=10000
 ```
@@ -52,7 +52,7 @@ VITE_SGS_SDK_TIMEOUT_MS=10000

 ```env
 VITE_API_BASE_URL=http://1.92.206.90:3001/app-api
-VITE_SGS_H5_ENGINE_URL=http://1.92.206.90:3001/h5-sdk
+VITE_SGS_H5_ENGINE_URL=http://1.92.206.90:3001/engine/index.html
 VITE_SGS_SDK_SCRIPT_URL=http://1.92.206.90:3001/sdk/sgs-map-sdk.min.js
 VITE_SGS_SDK_ORIGIN=http://1.92.206.90:3001
 ```
@@ -435,7 +435,7 @@ export const createGuideRepository = () => {
 | --- | --- | --- |
 | `static` | 本地 clean nav-assets | `ThreeMap` |
 | `api` | 后端 SGS App API | 仍可用 `ThreeMap` 或本地渲染 |
-| `sdk` | 后端 SGS App API | `SgsMapRenderer` |
+| `sdk` | 后端 SGS App API | 当前仍为 `ThreeMap`；SDK iframe renderer 尚未接入 |

 不要把 `sdk` 理解成“页面直接调用 `SGSMapSDK.getFloorPois()`”。数据仍从 Repository 进来，SDK 只做地图渲染和交互命令。

@@ -447,7 +447,7 @@ export const createGuideRepository = () => {
 - 调用 `guideUseCase.searchPois(keyword)`
 - 调用 `guideUseCase.getPoiById(id)`
 - 传 `GuideLocationPreview.positionGltf` 给地图聚焦
- 通过 `GuideMapShell` 选择 `ThreeMap` 或 `SgsMapRenderer`
+- 当前 `GuideMapShell` 固定使用 `ThreeMap`；启用 SDK iframe renderer 需要单独功能任务

 禁止展示层做的事：

@@ -478,7 +478,7 @@ await service.getFloorPois(floorId)
 3. 新增 `SgsSdkGuideRepository`，实现现有 `GuideRepository` interface。
 4. 新增仓库工厂，根据 `dataSourceConfig.mode` 选择 static 或 SGS 后端数据。
 5. 让 `guideUseCase` 使用仓库工厂，不改页面调用方式。
-6. 在 `sdk` 模式下让 `GuideMapShell` 继续选择 `SgsMapRenderer`，但 POI/楼层数据仍来自 `GuideUseCase`。
+6. 保持当前 `GuideMapShell` 使用 `ThreeMap`；若产品启用 iframe renderer，单独实施并保持 POI/楼层数据来自 `GuideUseCase`。
 7. 增加数据健康检查脚本或开发命令，校验楼层、POI、空间面、导航目的地计数。
 8. 通过 H5 浏览器检查搜索、楼层切换、POI 聚焦、位置预览。

@@ -530,9 +530,9 @@ pnpm build:h5

 - `static` 模式仍可加载本地 3D/POI。
 - `api` 模式能展示后端楼层和 POI，渲染器不变。
- `sdk` 模式能加载 SGS 地图基座，楼层切换与 POI 聚焦可用。
- SDK 失败时有错误态，不出现空白地图。
- 顶部 tabs、搜索、楼层控件、详情卡片不被 iframe/canvas 遮挡。
+- 当前 `sdk` 模式仍以 `ThreeMap` 渲染，验证后端数据与本地三维模型正常显示。
+- SDK Engine 仅在未来 iframe renderer 接入时验证：`/engine/index.html` 不是 SPA fallback、资源可加载、并完成 `HELLO` -> `ENGINE_READY`。
+- 顶部 tabs、搜索、楼层控件、详情卡片不被 canvas 遮挡；未来 iframe renderer 也必须满足该约束。

 ## 12. 上线前阻断项

--- a/src/config/dataSource.ts
+++ b/src/config/dataSource.ts
@@ -4,8 +4,9 @@ export type ConfiguredAudioLanguage = 'zh-CN' | 'yue-HK' | 'en-US'

 const allowedModes = new Set<DataSourceMode>(['static', 'api', 'sdk'])
 const allowedGuideContentModes = new Set<GuideContentDataSourceMode>(['static', 'remote', 'mock'])
-const defaultSdkScriptUrl = '/static/sgs-map-sdk/index.global.js?v=2.4.1'
-const defaultSgsEngineUrl = '/h5-sdk'
+export const SGS_MAP_SDK_VERSION = '2.5.0'
+const defaultSdkScriptUrl = `/static/sgs-map-sdk/index.global.js?v=${SGS_MAP_SDK_VERSION}`
+const defaultSgsEngineUrl = '/engine/index.html'
 const defaultSdkTimeoutMs = 5000
 const defaultApiBaseUrl = '/app-api'
 const defaultSgsMapId = '1'
--- a/static/sgs-map-sdk/README.md
+++ b/static/sgs-map-sdk/README.md
@@ -1,8 +1,10 @@
 # SGS Map SDK 交付包

-> **版本**：V2.4.0
+> **本项目同步版本**：V2.5.0
 > **定位**：深圳自然博物馆统一三维高精地图导航服务平台 H5 SDK

+> 发布源的 README 标题仍保留 V2.4.0，CHANGELOG 最高仍为 2.4.1；本项目以 `package.json`、`dist` 产物自报版本、SHA-256 和 2.5 Engine 迁移报告为发布依据，不把这份旧标题视为 2.5.0 验证记录。
+
 欢迎接入 SGS Map SDK！本 SDK 将复杂的 WebGL 三维渲染、GLB 模型管线与 NavMesh 物理寻路引擎封装在服务端基座中，业务端（H5 / 大屏 / 小程序）只需通过几行代码即可极速唤起 3D 地图。

 ## 📁 目录结构
@@ -35,11 +37,11 @@ sgs-map-sdk-release/

 1. **`sdkUrl`（渲染基座地址）**：
   - 释义：独立渲染基座的 URL 路径，SDK 会自动在您的页面中创建一个不可见的 iframe 或 Web-View 连接到这里。
-   - **请联系地图管理平台管理员获取最新的正式/测试域名**，例如：`https://map.museum.com/h5-sdk`。
+   - **请联系地图管理平台管理员获取最新的正式/测试域名**，例如：`https://map.museum.com/engine/index.html`。

 2. **`targetOrigin`（安全通信域）**：
   - 释义：这是指**地图渲染基座的来源域名**（即 `sdkUrl` 的 Origin）。为了安全，SDK 只接收来自该域名 iframe 的消息。
-   - 配置要求：请传入您的地图基座部署域名，例如：`https://map.museum.com`。如果不传，SDK 会自动从 `sdkUrl` 参数推导。注意：**不要**填成您业务页面的域名（业务页面的域名是交给 h5-sdk 做白名单校验的）。
+   - 配置要求：请传入独立 SDK Engine 的部署域名，例如：`https://map.museum.com`。如果不传，SDK 会自动从 `sdkUrl` 参数推导。注意：**不要**填成业务页面的域名。

 ## 📦 独立渲染基座部署与版本关系

--- a/static/sgs-map-sdk/index.d.mts
+++ b/static/sgs-map-sdk/index.d.mts
@@ -932,11 +932,11 @@ declare namespace utils {
 /**
 * SGS 3D 地图 H5 SDK 入口类
 *
- * <p>通过 iframe 嵌入 /h5-sdk 底座页面，以 postMessage 进行双向通信。
+ * <p>通过 iframe 嵌入独立发布的 /engine/index.html 渲染引擎，以 postMessage 进行双向通信。
 * <p>所有需要后端数据的操作均通过 postMessage 指令由底座代理，
 *    Demo / 宿主不允许直连后端 API。
 *
- * @version 2.4.1
+ * @version 2.5.0
 */
 declare class SGSMapSDK extends EventEmitter<SGSMapEvents> {
    static utils: typeof utils;
--- a/static/sgs-map-sdk/index.d.ts
+++ b/static/sgs-map-sdk/index.d.ts
@@ -932,11 +932,11 @@ declare namespace utils {
 /**
 * SGS 3D 地图 H5 SDK 入口类
 *
- * <p>通过 iframe 嵌入 /h5-sdk 底座页面，以 postMessage 进行双向通信。
+ * <p>通过 iframe 嵌入独立发布的 /engine/index.html 渲染引擎，以 postMessage 进行双向通信。
 * <p>所有需要后端数据的操作均通过 postMessage 指令由底座代理，
 *    Demo / 宿主不允许直连后端 API。
 *
- * @version 2.4.1
+ * @version 2.5.0
 */
 declare class SGSMapSDK extends EventEmitter<SGSMapEvents> {
    static utils: typeof utils;
--- a/static/sgs-map-sdk/index.global.js
+++ b/static/sgs-map-sdk/index.global.js
--- a/static/sgs-map-sdk/index.global.js.map
+++ b/static/sgs-map-sdk/index.global.js.map
--- a/static/sgs-map-sdk/index.mjs
+++ b/static/sgs-map-sdk/index.mjs
--- a/static/sgs-map-sdk/index.mjs.map
+++ b/static/sgs-map-sdk/index.mjs.map
--- a/static/sgs-map-sdk/package.json
+++ b/static/sgs-map-sdk/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@sgs/map-sdk",
-  "version": "2.4.1",
+  "version": "2.5.0",
  "description": "SGS Map SDK API contract copy for frontend-miniapp; iframe runtime is not enabled by this project",
  "main": "./index.global.js",
  "types": "./index.d.ts",
@@ -22,7 +22,8 @@
    "CHANGELOG.md",
    "sdk-quickstart.md",
    "sdk-api-reference.md",
-    "sdk-protocol.md"
+    "sdk-protocol.md",
+    "sdk-bridge-contract.md"
  ],
  "devDependencies": {},
  "author": "SGS Team",
--- a/static/sgs-map-sdk/sdk-api-reference.md
+++ b/static/sgs-map-sdk/sdk-api-reference.md
@@ -1,8 +1,10 @@
 # SGS Map SDK API Reference

-> 版本: V2.3.0
+> 本项目同步版本: V2.5.0
 > 适用对象: 第三方 H5、大屏、Kiosk、业务前端开发人员

+> 发布源保留了 V2.3.0 文档标题和历史 API 注释；实际发行版本以 `package.json` 与 `dist` 产物自报的 2.5.0 为准。本文不表示本项目已经接入或验证 SDK iframe renderer。
+
 本文档按公开 SDK 方法组织，说明初始化参数、事件、常用 API、返回值和错误处理。快速接入请先阅读 `sdk-quickstart.md`，底层通信协议请阅读 `sdk-protocol.md`。

 ## 1. 接入入口
@@ -14,7 +16,7 @@
 <script>
  const map = new SGSMapSDK({
    container: 'map-container',
-    sdkUrl: 'https://map.example.com/h5-sdk',
+    sdkUrl: 'https://map.example.com/engine/index.html',
    targetOrigin: 'https://map.example.com',
    floorId: 1
  });
@@ -24,7 +26,7 @@
 如果 SDK 已随 `sgs-frontend-map` 发布到静态目录：

 ```html
-<script src="/sdk/sgs-map-sdk.min.js?v=2.3.0"></script>
+<script src="/sdk/sgs-map-sdk.min.js?v=2.5.0"></script>
 ```

 ### ESM
@@ -34,7 +36,7 @@ import SGSMapSDK from './dist/index.mjs';

 const map = new SGSMapSDK({
  container: document.getElementById('map-container')!,
-  sdkUrl: 'https://map.example.com/h5-sdk',
+  sdkUrl: 'https://map.example.com/engine/index.html',
  targetOrigin: 'https://map.example.com',
  floorId: 1
 });
@@ -57,7 +59,7 @@ interface SGSMapSDKOptions {
 | 字段 | 必填 | 默认值 | 说明 |
 |------|------|--------|------|
 | `container` | 是 | 无 | 地图 iframe 挂载容器，可传 DOM id 或 HTMLElement |
-| `sdkUrl` | 否 | `/h5-sdk` | H5 SDK 渲染基座地址 |
+| `sdkUrl` | 否 | `/engine/index.html` | 独立发布的 SDK 渲染引擎地址 |
 | `targetOrigin` | 否 | 从 `sdkUrl` 推导 | `postMessage` 安全通信域，生产环境建议显式填写 |
 | `floorId` | 否 | `1` | 初始楼层 ID，支持字符串或数字 |
 | `mapId` | 否 | `1` | 地图 ID，当前由 SDK 实例保存 |
@@ -107,7 +109,7 @@ window.addEventListener('beforeunload', () => {

 ### `getVersion(): string`

-返回 SDK 版本号，v2.3.0 返回 `"2.3.0"`。
+返回 SDK 版本号；本项目同步的 2.5.0 Bridge 返回 `"2.5.0"`。

 ### `getState(): Promise<any>`

@@ -654,9 +656,9 @@ try {
 ## 15. 第三方接入检查清单

 - 页面中存在 SDK 挂载容器，且容器有稳定宽高。
- `sdkUrl` 可在浏览器直接访问，并能加载 `/h5-sdk`。
+- `sdkUrl` 可在浏览器直接访问，并能加载独立发布的 `/engine/index.html`。
 - `targetOrigin` 与 `sdkUrl` 的 Origin 一致。
 - 所有地图控制 API 在 `await map.whenReady()` 后调用。
 - 坐标统一使用 GLB/Three.js 米制坐标，水平面为 `x/z`。
 - 页面卸载时调用 `map.destroy()`。
- 生产发布时 SDK 版本、基座版本和后端 Manifest 的 `sdkVersion` 保持 `2.3.0`。
+- 生产发布时 SDK、Engine 与后端 Manifest 的 `sdkVersion` 必须保持兼容；本次 Bridge 为 `2.5.0`，上线前需验证 `/engine/index.html` 真实加载 SDK Engine 并完成 `HELLO` -> `ENGINE_READY`。
--- a/static/sgs-map-sdk/sdk-bridge-contract.md
+++ b/static/sgs-map-sdk/sdk-bridge-contract.md
--- a/static/sgs-map-sdk/sdk-quickstart.md
+++ b/static/sgs-map-sdk/sdk-quickstart.md
@@ -1,6 +1,8 @@
 # SGS Map SDK 快速接入指南

-> 版本: V2.3.0 | 支持终端: H5 浏览器、大屏终端、微信小程序
+> 本项目同步版本: V2.5.0 | 支持终端: H5 浏览器、大屏终端、微信小程序
+
+> 发布源保留了 V2.3.0 文档标题和历史 API 注释；实际发行版本以 `package.json` 与 `dist` 产物自报的 2.5.0 为准。本文只同步其公开接入资料，不声明未经本项目验证的 iframe renderer 能力。

 ## 1. 引入方式

@@ -18,7 +20,7 @@ SDK 提供多种模块规范的产出文件，适配不同的应用场景：
 如果 SDK 已由 `sgs-frontend-map` 发布到前端静态目录，也可以直接使用浏览器发布文件：

 ```html
-<script src="/sdk/sgs-map-sdk.min.js?v=2.3.0"></script>
+<script src="/sdk/sgs-map-sdk.min.js?v=2.5.0"></script>
 ```

 ### 1.2 ESM Import (Webpack / Vite / Next.js)
@@ -33,7 +35,7 @@ const sdk = new SGSMapSDK({ ... });
 在微信小程序中，无需引入外壳 SDK，直接通过 `web-view` 组件加载地图基座，并通过 URL 传递参数。
 ```html
 <!-- 小程序 WXML -->
-<web-view src="https://map.museum.com/h5-sdk?floorId=1&mode=miniapp"></web-view>
+<web-view src="https://map.museum.com/engine/index.html?floorId=1&mode=miniapp"></web-view>
 ```

 ### 1.4 渲染基座地址
@@ -41,7 +43,7 @@ const sdk = new SGSMapSDK({ ... });
 SDK 通过 `sdkUrl` 连接独立渲染基座。正式接入时请使用地图服务平台管理员提供的基座地址，例如：

 ```text
-https://map.museum.com/h5-sdk
+https://map.museum.com/engine/index.html
 ```

 发布包内附带 `demo/` 目录，是一个完整的 SDK 能力展示页面。运行方式：
@@ -61,7 +63,7 @@ npx -y serve . -l 5555
 ```javascript
 const map = new SGSMapSDK({
  container: 'map-container',              // 挂载的 DOM 容器 ID
-  sdkUrl: 'https://map.museum.com/h5-sdk', // 渲染基座的 URL
+  sdkUrl: 'https://map.museum.com/engine/index.html', // 独立渲染引擎 URL
  targetOrigin: 'https://map.museum.com',  // [重要] 安全防范，配置只允许该域名通信
  floorId: 1,                              // 初始楼层 ID
  timeout: 5000                            // API 调用的默认超时时间（毫秒）
--- a/tests/unit/SgsMapSdkReleaseContract.spec.ts
+++ b/tests/unit/SgsMapSdkReleaseContract.spec.ts
@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const sdkDirectory = resolve(process.cwd(), 'static/sgs-map-sdk')
+const readSdkFile = (name: string) => readFileSync(resolve(sdkDirectory, name), 'utf8')
+
+describe('SGS Map SDK 2.5.0 release contract', () => {
+  it('keeps the local package, bridge self-report, and default Engine path aligned', () => {
+    const packageJson = JSON.parse(readSdkFile('package.json')) as { version: string }
+    const bridge = readSdkFile('index.global.js')
+    const dataSource = readFileSync(resolve(process.cwd(), 'src/config/dataSource.ts'), 'utf8')
+
+    expect(packageJson.version).toBe('2.5.0')
+    expect(bridge).toContain('"2.5.0"')
+    expect(bridge).toContain('/engine/index.html')
+    expect(dataSource).toContain("SGS_MAP_SDK_VERSION = '2.5.0'")
+    expect(dataSource).toContain("const defaultSgsEngineUrl = '/engine/index.html'")
+  })
+
+  it('ships every runtime bridge artifact required by the flattened package', () => {
+    [
+      'index.global.js',
+      'index.global.js.map',
+      'index.mjs',
+      'index.mjs.map',
+      'index.d.ts',
+      'index.d.mts'
+    ].forEach((file) => {
+      expect(existsSync(resolve(sdkDirectory, file))).toBe(true)
+    })
+  })
+})
--- a/tests/unit/SgsMapService.spec.ts
+++ b/tests/unit/SgsMapService.spec.ts
@@ -32,8 +32,8 @@ const createHarness = async () => {

  const service = new SgsMapService({
    container: {} as HTMLElement,
-    scriptUrl: '/static/sgs-map-sdk/index.global.js?v=2.4.1',
-    sdkUrl: '/h5-sdk',
+    scriptUrl: '/static/sgs-map-sdk/index.global.js?v=2.5.0',
+    sdkUrl: '/engine/index.html',
    targetOrigin: 'https://map.example.com',
    floorId: 'L1',
    timeout: 7000
@@ -42,19 +42,31 @@ const createHarness = async () => {

  await vi.waitFor(() => expect(SDKConstructor).toHaveBeenCalledOnce())
  listeners.get('ready')?.({
-    engineVersion: '2.4.1',
+    engineVersion: '2.5.0',
    protocolVersion: 2
  } as never)
  await ready

-  return { sdk, service }
+  return { sdk, service, SDKConstructor }
 }

 beforeEach(() => {
  loadSgsMapScript.mockReset()
 })

-describe('SGS Map SDK 2.4.1 service adapter', () => {
+describe('SGS Map SDK 2.5.0 service adapter', () => {
+  it('向 SDK 构造器传入完整的 Engine 桥接配置', async () => {
+    const { SDKConstructor } = await createHarness()
+
+    expect(SDKConstructor).toHaveBeenCalledWith({
+      container: expect.any(Object),
+      sdkUrl: '/engine/index.html',
+      targetOrigin: 'https://map.example.com',
+      floorId: 'L1',
+      timeout: 7000
+    })
+  })
+
  it('透传楼层强制刷新选项和统一命令超时', async () => {
    const { sdk, service } = await createHarness()

--- a/vite.config.ts
+++ b/vite.config.ts
@@ -30,7 +30,7 @@ export default defineConfig(({ mode }) => {
  )
  const buildPlatform = process.env.UNI_PLATFORM === 'mp-weixin' ? 'mp-weixin' : 'h5'
  const appApiProxyTarget = normalizeEnvUrl(env.DEV_PROXY_APP_API_TARGET, 'http://localhost:3001')
-  const h5SdkProxyTarget = normalizeEnvUrl(env.DEV_PROXY_H5_SDK_TARGET, appApiProxyTarget)
+  const engineProxyTarget = normalizeEnvUrl(env.DEV_PROXY_ENGINE_TARGET, appApiProxyTarget)
  const sdkProxyTarget = normalizeEnvUrl(env.DEV_PROXY_SDK_TARGET, appApiProxyTarget)
  const museumAssetsProxyTarget = normalizeEnvUrl(env.DEV_PROXY_MUSEUM_ASSETS_TARGET, 'http://localhost:9000')
  const minioProxyTarget = normalizeEnvUrl(env.DEV_PROXY_MINIO_TARGET, appApiProxyTarget)
@@ -51,8 +51,8 @@ export default defineConfig(({ mode }) => {
          target: appApiProxyTarget,
          changeOrigin: true
        },
-        '/h5-sdk': {
-          target: h5SdkProxyTarget,
+        '/engine': {
+          target: engineProxyTarget,
          changeOrigin: true
        },
        '/sdk': {