升级 SGS Map SDK 至 2.5.0

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` 参数推导。注意：**不要**填成业务页面的域名。
 
 ## 📦 独立渲染基座部署与版本关系
 

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;

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;

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",

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`。

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 调用的默认超时时间（毫秒）