升级 SGS Map SDK 至 2.5.0

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. 上线前阻断项