升级 SGS Map SDK 至 2.5.0

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