1161 lines
25 KiB
Markdown
1161 lines
25 KiB
Markdown
# SGS Map SDK Bridge 契约文档
|
||
|
||
> 版本: 2.5.0 | 最后更新: 2026-07-15 | 基于独立 `/engine/` 渲染引擎实际实现
|
||
|
||
## 概述
|
||
|
||
本文档记录 SGS Map SDK（客户端 JS 库）与独立发布的 `/engine/` 渲染引擎之间的 `postMessage` 通信契约。运行时引擎源码位于 `sgs-frontend-map/sdk-engine`，发布产物位于 `sgs-map-sdk-release/engine`。
|
||
|
||
**核心架构**:
|
||
```
|
||
┌─────────────┐ postMessage ┌───────────────────┐ REST API ┌──────────┐
|
||
│ 宿主页面 │ ◄───────────► │ /engine/ 引擎 │ ◄──────────► │ 后端 │
|
||
│ (SDK.js) │ SGS_MAP_* │ (page.tsx iframe) │ /app-api/* │ Spring │
|
||
└─────────────┘ └───────────────────┘ └──────────┘
|
||
```
|
||
|
||
## 通信协议
|
||
|
||
### 请求格式（宿主 → 基座）
|
||
|
||
```ts
|
||
{
|
||
type: 'SGS_MAP_COMMAND',
|
||
action: string, // 指令名（如 'CHANGE_FLOOR'）
|
||
requestId: string, // 唯一请求 ID，用于匹配响应
|
||
payload: object // 指令参数
|
||
}
|
||
```
|
||
|
||
### 响应格式（基座 → 宿主）
|
||
|
||
```ts
|
||
{
|
||
type: 'SGS_MAP_RESPONSE',
|
||
action: string, // 原样回显请求的 action（A2.6 规约）
|
||
requestId: string, // 原样回显请求的 requestId
|
||
payload: object, // 响应数据（含 success: boolean）
|
||
error?: { // 仅失败时存在
|
||
code: string,
|
||
message: string
|
||
}
|
||
}
|
||
```
|
||
|
||
### 事件格式（基座 → 宿主，主动推送）
|
||
|
||
```ts
|
||
{
|
||
type: 'SGS_MAP_EVENT',
|
||
action: string, // 事件名（如 'ENGINE_READY', 'ON_POI_CLICK'）
|
||
payload: object
|
||
}
|
||
```
|
||
|
||
### Origin 安全校验
|
||
|
||
基座通过 URL 参数 `?targetOrigin=<origin>` 启用 origin 白名单校验。若 `targetOrigin` 非 `*` 且与 `event.origin` 不匹配，消息将被静默丢弃。
|
||
|
||
---
|
||
|
||
## Bridge 支持矩阵
|
||
|
||
> ✅ = 代码中存在对应 `case` 分支，已实际实现
|
||
> ❌ = 代码中无对应 `case` 分支
|
||
|
||
| # | SDK 方法名 | postMessage action | /engine/ 支持 | 最低版本 | 类别 |
|
||
|---|-----------|-------------------|:---:|---------|------|
|
||
| 1 | `自动握手` | `HELLO` | ✅ | 1.0.0 | 生命周期 |
|
||
| 2 | `changeFloor()` | `CHANGE_FLOOR` | ✅ | 1.0.0 | 地图控制 |
|
||
| 3 | `focusTo()` | `FOCUS_TO` | ✅ | 1.0.0 | 地图控制 |
|
||
| 4 | `setViewMode()` | `SET_VIEW_MODE` | ✅ | 2.3.0 | 地图控制 |
|
||
| 5 | `addMarker()` | `ADD_MARKER` / `ADD_BUSINESS_MARKER` | ✅ | 1.0.0 | 图钉 |
|
||
| 6 | `removeMarker()` | `REMOVE_MARKER` / `REMOVE_BUSINESS_MARKER` | ✅ | 1.0.0 | 图钉 |
|
||
| 7 | `clearMarkers()` | `CLEAR_MARKERS` | ✅ | 1.0.0 | 图钉 |
|
||
| 8 | `planRoute()` / `planRouteV2()` | `PLAN_ROUTE` | ✅ | 1.0.0 | 路径规划 |
|
||
| 9 | `highlightPolygon()` | `HIGHLIGHT_POLYGON` | ✅ | 1.0.0 | 地图控制 |
|
||
| 10 | `clearRoute()` | `CLEAR_ROUTE` | ✅ | 1.0.0 | 路径规划 |
|
||
| 11 | `resetView()` | `RESET_VIEW` | ✅ | 1.0.0 | 地图控制 |
|
||
| 12 | `getState()` | `GET_STATE` | ✅ | 1.0.0 | 状态查询 |
|
||
| 13 | `toggleLayer()` | `TOGGLE_LAYER` | ✅ | 1.5.0 | 图层控制 |
|
||
| 14 | `setVisibleLayers()` | `SET_VISIBLE_TYPES` | ✅ | 1.5.0 | 图层控制 |
|
||
| 15 | `getManifest()` | `GET_MANIFEST` | ✅ | 2.1.0 | 数据查询 |
|
||
| 16 | `loadFloorBundle()` | `LOAD_FLOOR_BUNDLE` | ✅ | 2.1.0 | 数据查询 |
|
||
| 17 | `getFloorPois()` | `GET_FLOOR_POIS` | ✅ | 2.1.0 | 数据查询 |
|
||
| 18 | `getPois()` | `GET_POIS` | ✅ | 1.0.0 | 数据查询 |
|
||
| 19 | `getSpaces()` | `GET_SPACES` | ✅ | 2.1.0 | 数据查询 |
|
||
| 20 | `getGuideStops()` | `GET_GUIDE_STOPS` | ✅ | 2.1.0 | 数据查询 |
|
||
| 21 | `getGuideStopsByHall()` | `GET_GUIDE_STOPS_BY_HALL` | ✅ | 2.1.0 | 数据查询 |
|
||
| 22 | `getNavigablePlaces()` | `GET_NAVIGABLE_PLACES` | ✅ | 2.3.0 | 数据查询 |
|
||
| 23 | `preloadFloor()` | `PRELOAD_FLOOR` | ✅ | 2.1.0 | 性能优化 |
|
||
| 24 | `clearModelCache()` | `CLEAR_MODEL_CACHE` | ✅ | 2.1.0 | 性能优化 |
|
||
| 25 | `getPerformanceStats()` | `GET_PERFORMANCE_STATS` | ✅ | 2.1.0 | 诊断 |
|
||
| 26 | `getDiagnostics()` | `GET_DIAGNOSTICS` | ✅ | 2.3.0 | 诊断 |
|
||
| 27 | `getFloorDiagnostics()` | `GET_FLOOR_DIAGNOSTICS` | ✅ | 2.3.0 | 诊断 |
|
||
|
||
### 仅 mock-release 模式专用指令（非公开 SDK 方法）
|
||
|
||
| # | postMessage action | /engine/ 支持 | 说明 |
|
||
|---|-------------------|:---:|------|
|
||
| M1 | `GET_RELEASE_MANIFEST` | ✅ | 仅 `env=mock-release` 时可用 |
|
||
| M2 | `GET_MODEL_RESOURCES` | ✅ | 仅 `env=mock-release` 时可用 |
|
||
| M3 | `GET_LAYER_TREE` | ✅ | 仅 `env=mock-release` 时可用 |
|
||
| M4 | `LOAD_MOCK_RELEASE_ROUTE` | ✅ | 仅 `env=mock-release` 时可用 |
|
||
|
||
> 以上 M1–M4 已在 SDK v2.3.0 中标记为废弃 (`deprecated`)，新接入方不应使用。
|
||
|
||
---
|
||
|
||
## 各指令详细规格
|
||
|
||
---
|
||
|
||
### 1. HELLO
|
||
|
||
握手协议。SDK 创建 iframe 后自动发送，基座收到后立即触发 `ENGINE_READY` 事件。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `HELLO` |
|
||
| **SDK 方法** | 自动握手（SDK 内部调用，不暴露公开方法） |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{ version?: string } // SDK 版本号（可选）
|
||
```
|
||
|
||
**成功响应**: 无显式 `SGS_MAP_RESPONSE`。基座通过 `SGS_MAP_EVENT` 发送 `ENGINE_READY`:
|
||
```ts
|
||
// type: 'SGS_MAP_EVENT', action: 'ENGINE_READY'
|
||
{
|
||
engineVersion: "2.0.0",
|
||
protocolVersion: 2,
|
||
sdkVersion: "2.3.0",
|
||
floorId: string | number,
|
||
poiCount: number,
|
||
hasRouteNetwork: boolean
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 2. CHANGE_FLOOR
|
||
|
||
切换当前显示楼层。触发 GPU 显存回收、状态重置和新楼层数据加载。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `CHANGE_FLOOR` |
|
||
| **SDK 方法** | `sdk.changeFloor(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId: string | number // 目标楼层 ID 或 floorCode（real-preview 模式支持）
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
floorId: string | number // 实际切换到的楼层 ID
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A（当前实现始终返回 success）
|
||
|
||
**特殊行为**:
|
||
- 若目标楼层与当前楼层相同，直接返回 success，不触发重新加载（防抖）
|
||
- `real-preview` 模式下支持通过 `floorCode`（如 `"L2"`）匹配楼层
|
||
|
||
---
|
||
|
||
### 3. FOCUS_TO
|
||
|
||
镜头聚焦到指定 POI、坐标或场景节点，支持自适应半径 FlyTo 动画。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `FOCUS_TO` |
|
||
| **SDK 方法** | `sdk.focusTo(node)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**（三种模式）:
|
||
|
||
```ts
|
||
// 模式 1: 坐标聚焦
|
||
{
|
||
type: "coord",
|
||
x: number, // GLB X 坐标（米）
|
||
z: number, // GLB Z 坐标（米）
|
||
y?: number, // 高度，默认 0.2
|
||
radius?: number // 聚焦半径，默认 3.0
|
||
}
|
||
|
||
// 模式 2: POI ID 聚焦
|
||
{
|
||
type: "poiId",
|
||
value: string | number // POI ID
|
||
}
|
||
|
||
// 模式 3: 节点名聚焦
|
||
{
|
||
type: "nodeName",
|
||
value: string // GLB 节点名或 POI 名称
|
||
}
|
||
|
||
// 模式 4: 字符串简写
|
||
"Hall_Dinosaur" // 直接传 POI 名称字符串
|
||
```
|
||
|
||
**成功响应**: 无显式响应（fire-and-forget 模式）
|
||
|
||
**错误响应**: 无显式响应，仅 console.warn
|
||
|
||
**备注**: 基座会同时在 POI 列表和讲解点列表中检索匹配项，按 `name` / `nameEn` / `id` / `guideStopId` 匹配。
|
||
|
||
---
|
||
|
||
### 4. SET_VIEW_MODE
|
||
|
||
切换 2D 俯视 / 3D 透视模式。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `SET_VIEW_MODE` |
|
||
| **SDK 方法** | `sdk.setViewMode(mode)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.3.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
mode: "2d" | "3d"
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
mode: "2d" | "3d"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_INVALID_MODE",
|
||
message: "Invalid mode: <value>. Expected '2d' or '3d'"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. ADD_MARKER / ADD_BUSINESS_MARKER
|
||
|
||
添加业务图钉。两个 action 名共享同一处理逻辑，均可使用。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `ADD_MARKER` 或 `ADD_BUSINESS_MARKER` |
|
||
| **SDK 方法** | `sdk.addMarker(config)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
id: string, // 唯一图钉 ID（重复 id 会覆盖已有图钉）
|
||
name: string, // 显示名称
|
||
iconUrl: string, // 图标 URL
|
||
anchorNodeName?: string, // 可选，绑定到 GLB 场景节点
|
||
position?: [number, number, number] // [x, y, z] 世界坐标
|
||
}
|
||
```
|
||
|
||
**成功响应**: 无显式响应（fire-and-forget 模式）
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 6. REMOVE_MARKER / REMOVE_BUSINESS_MARKER
|
||
|
||
移除指定业务图钉。两个 action 名共享同一处理逻辑。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `REMOVE_MARKER` 或 `REMOVE_BUSINESS_MARKER` |
|
||
| **SDK 方法** | `sdk.removeMarker(markerId)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
markerId: string // 要移除的图钉 ID
|
||
}
|
||
```
|
||
|
||
**成功响应**: 无显式响应（fire-and-forget 模式）
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 7. CLEAR_MARKERS
|
||
|
||
清空所有业务图钉。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `CLEAR_MARKERS` |
|
||
| **SDK 方法** | `sdk.clearMarkers()` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**: `{}` （空对象）
|
||
|
||
**成功响应**: 无显式响应（fire-and-forget 模式）
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 8. PLAN_ROUTE
|
||
|
||
路径规划。支持同层和跨层 NavMesh 寻路，起终点支持 POI 名称、POI ID 和坐标三种模式。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `PLAN_ROUTE` |
|
||
| **SDK 方法** | `sdk.planRoute(from, to, options?, timeout?)` / `sdk.planRouteV2(...)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
startNode: string | SgsMapNode, // 起点（POI 名称字符串或结构化节点）
|
||
endNode: string | SgsMapNode, // 终点
|
||
options?: {
|
||
mode?: "walk" | "accessible", // 路线模式
|
||
wheelchair?: boolean // 无障碍路线
|
||
}
|
||
}
|
||
```
|
||
|
||
其中 `SgsMapNode`:
|
||
```ts
|
||
type SgsMapNode =
|
||
| { type: "coord"; floorId: string | number; x: number; z: number }
|
||
| { type: "poiId"; value: string | number }
|
||
| string // POI 名称
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
distance: number, // 总距离（米）
|
||
duration: number, // 预计耗时（秒）
|
||
segments: Array<{ // 分段路线
|
||
floorId: string | number,
|
||
transferType: "WALK" | "ELEVATOR" | "STAIRS" | "ESCALATOR",
|
||
points: Array<{ x: number; y: number; z: number }>,
|
||
pathGeoJson?: string
|
||
}>
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_INVALID_PARAMS" | "ERR_ROUTING_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 9. HIGHLIGHT_POLYGON
|
||
|
||
高亮 POI 关联的多边形边界或空间面。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `HIGHLIGHT_POLYGON` |
|
||
| **SDK 方法** | `sdk.highlightPolygon(nodeName)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
nodeName?: string, // POI/空间面名称
|
||
name?: string, // 备选字段
|
||
id?: string | number // 备选字段
|
||
}
|
||
```
|
||
|
||
**成功响应**: 无显式响应（fire-and-forget 模式）
|
||
|
||
**错误响应**: N/A
|
||
|
||
**备注**: 先在 POI 列表中查找（匹配 `polygonWkt`），若无结果再在空间面列表中查找（匹配 `boundaryWkt`）。
|
||
|
||
---
|
||
|
||
### 10. CLEAR_ROUTE
|
||
|
||
清除当前导航路线。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `CLEAR_ROUTE` |
|
||
| **SDK 方法** | `sdk.clearRoute()` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**: `{}` （空对象）
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 11. RESET_VIEW
|
||
|
||
重置相机视角，清除聚焦和高亮状态，将视角模式恢复为 3D。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `RESET_VIEW` |
|
||
| **SDK 方法** | `sdk.resetView()` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**: `{}` （空对象）
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
**备注**: 不会清除导航路线（`routeSegments`），仅重置选中 POI、聚焦目标和高亮节点。视角模式恢复为 `"3d"`。
|
||
|
||
---
|
||
|
||
### 12. GET_STATE
|
||
|
||
获取基座当前内部状态快照。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_STATE` |
|
||
| **SDK 方法** | `sdk.getState()` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**: `{}` （空对象）
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
floorId: string | number,
|
||
poiCount: number,
|
||
isNavActive: boolean,
|
||
engineVersion: "2.0.0",
|
||
routeSegments: any[],
|
||
activeSegmentIndex: number,
|
||
hasRouteNetwork: boolean,
|
||
spatialAreas: Array<{ id: any; name: string; wkt: string }>,
|
||
// mock-release 模式附加字段
|
||
envMode?: "mock-release",
|
||
floorCode?: string,
|
||
manifest?: { version: string; releaseId: string; totalFloors: number } | null
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 13. TOGGLE_LAYER
|
||
|
||
切换指定 POI 类型图层的显示/隐藏。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `TOGGLE_LAYER` |
|
||
| **SDK 方法** | `sdk.toggleLayer(types, visible, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.5.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
types: string[], // POI 类型列表（如 ["TOILET", "ELEVATOR"]）
|
||
visible: boolean // true = 显示, false = 隐藏
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
visibleTypes: string[] // 操作后的完整可见类型白名单
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 14. SET_VISIBLE_TYPES
|
||
|
||
设置当前可见的图层类型列表（完全替换模式）。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `SET_VISIBLE_TYPES` |
|
||
| **SDK 方法** | `sdk.setVisibleLayers(types, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.5.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
types: string[] // 可见类型列表
|
||
}
|
||
```
|
||
|
||
特殊值语义:
|
||
- `[]` → 切换为 `space` 模式（仅显示空间面）
|
||
- `["space"]` → 空间面模式
|
||
- `["guide_stop"]` → 仅讲解点
|
||
- `["poi"]` → 仅 POI
|
||
- 其他 → 自定义类型白名单
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
visibleTypes: string[]
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 15. GET_MANIFEST
|
||
|
||
获取地图 Manifest（地图名称、楼层摘要、能力声明）。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_MANIFEST` |
|
||
| **SDK 方法** | `sdk.getManifest(timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
mapId?: string | number // 地图 ID，默认 "1"
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
mapId: string | number,
|
||
mapName: string,
|
||
sdkVersion: string,
|
||
protocolVersion: number,
|
||
dataVersion: string,
|
||
updatedAt: string,
|
||
coordinateSystem: string,
|
||
floors: SgsSdkFloorSummary[],
|
||
capabilities: { ... }
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_NETWORK" | "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 16. LOAD_FLOOR_BUNDLE
|
||
|
||
一次性加载指定楼层的完整数据包（模型、POI、空间面、讲解点、路网摘要）。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `LOAD_FLOOR_BUNDLE` |
|
||
| **SDK 方法** | `sdk.loadFloorBundle(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId?: string | number // 目标楼层 ID，默认当前楼层
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
floor: { floorId, floorCode, floorName, sortOrder },
|
||
model: { modelUrl, fallbackModelUrl, compressionType, sizeBytes },
|
||
pois: SgsPoi[],
|
||
spaces: SgsSpaceArea[],
|
||
guideStops: SgsGuideStop[],
|
||
routeSummary: { hasRouteNetwork, nodeCount, edgeCount },
|
||
hiddenSceneNodeNames: string[],
|
||
dataVersion: string
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_NETWORK" | "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 17. GET_FLOOR_POIS
|
||
|
||
获取指定楼层 POI 列表。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_FLOOR_POIS` |
|
||
| **SDK 方法** | `sdk.getFloorPois(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId?: string | number // 目标楼层 ID，默认当前楼层
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
pois: SgsPoi[]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 18. GET_POIS
|
||
|
||
获取当前楼层 POI 列表（直接返回基座内存中的 POI 数据）。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_POIS` |
|
||
| **SDK 方法** | `sdk.getPois(floorCode, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 1.0.0 |
|
||
|
||
**请求 payload**: `{}` （空对象）
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
pois: any[], // 当前基座内存中的 POI 数组
|
||
floorCode: string // 当前楼层代码
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 19. GET_SPACES
|
||
|
||
获取指定楼层空间面列表。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_SPACES` |
|
||
| **SDK 方法** | `sdk.getSpaces(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId?: string | number // 目标楼层 ID，默认当前楼层
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
spaces: SgsSpaceArea[]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 20. GET_GUIDE_STOPS
|
||
|
||
获取指定楼层讲解点列表。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_GUIDE_STOPS` |
|
||
| **SDK 方法** | `sdk.getGuideStops(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId?: string | number // 目标楼层 ID，默认当前楼层
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
guideStops: SgsGuideStop[]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 21. GET_GUIDE_STOPS_BY_HALL
|
||
|
||
按展厅 ID 获取讲解点列表。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_GUIDE_STOPS_BY_HALL` |
|
||
| **SDK 方法** | `sdk.getGuideStopsByHall(hallId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
hallId: string | number // 必填，展厅 ID
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
guideStops: SgsGuideStop[]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_INVALID_PARAMS", // hallId 为空时
|
||
message: "hallId 不能为空"
|
||
}
|
||
// 或
|
||
{
|
||
code: "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 22. GET_NAVIGABLE_PLACES
|
||
|
||
获取指定楼层可导航目的地列表。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_NAVIGABLE_PLACES` |
|
||
| **SDK 方法** | `sdk.getNavigablePlaces(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.3.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId?: string | number // 目标楼层 ID，默认当前楼层
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
navigablePlaces: SgsNavigablePlace[]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_INVALID_PARAMS", // floorId 为空时
|
||
message: "floorId 不能为空"
|
||
}
|
||
// 或
|
||
{
|
||
code: "ERR_NETWORK" | "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 23. PRELOAD_FLOOR
|
||
|
||
后台预加载指定楼层的 bundle 数据到缓存（LRU，最多缓存 2 个楼层），不切换当前视图。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `PRELOAD_FLOOR` |
|
||
| **SDK 方法** | `sdk.preloadFloor(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId: string | number // 必填，要预加载的楼层 ID
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
cached: boolean, // true = 命中已有缓存, false = 新加载
|
||
loadMs?: number // 新加载时的耗时（仅 cached=false 时存在）
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_INVALID_PARAMS", // floorId 为空时
|
||
message: "floorId 不能为空"
|
||
}
|
||
// 或
|
||
{
|
||
code: "ERR_NETWORK" | "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 24. CLEAR_MODEL_CACHE
|
||
|
||
清空客户端 bundle 缓存。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `CLEAR_MODEL_CACHE` |
|
||
| **SDK 方法** | `sdk.clearModelCache()` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**: `{}` （空对象）
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 25. GET_PERFORMANCE_STATS
|
||
|
||
获取渲染基座的性能统计数据。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_PERFORMANCE_STATS` |
|
||
| **SDK 方法** | `sdk.getPerformanceStats(timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.1.0 |
|
||
|
||
**请求 payload**: `{}` （空对象）
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
currentFloorId: string | number,
|
||
manifestLoadMs?: number,
|
||
bundleLoadMs?: number,
|
||
modelParseMs?: number,
|
||
firstRenderMs?: number,
|
||
dracoUsed?: boolean,
|
||
fallbackUsed?: boolean
|
||
}
|
||
```
|
||
|
||
**错误响应**: N/A
|
||
|
||
---
|
||
|
||
### 26. GET_DIAGNOSTICS
|
||
|
||
获取地图整体诊断信息。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_DIAGNOSTICS` |
|
||
| **SDK 方法** | `sdk.getDiagnostics(timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.3.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
mapId?: string | number // 地图 ID，默认 "1"
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
mapId: string | number,
|
||
mapName: string,
|
||
sdkVersion: string,
|
||
status: "OK" | "WARN" | "ERROR",
|
||
floors: SgsFloorDiagnosticsSummary[],
|
||
summary: {
|
||
floorCount: number,
|
||
modelReadyFloorCount: number,
|
||
poiCount: number,
|
||
spaceCount: number,
|
||
guideStopCount: number,
|
||
navigablePlaceCount: number,
|
||
routeNodeCount: number,
|
||
routeEdgeCount: number
|
||
},
|
||
warnings: string[]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_NETWORK" | "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 27. GET_FLOOR_DIAGNOSTICS
|
||
|
||
获取单个楼层的详细诊断信息。
|
||
|
||
| 项目 | 值 |
|
||
|------|---|
|
||
| **postMessage action** | `GET_FLOOR_DIAGNOSTICS` |
|
||
| **SDK 方法** | `sdk.getFloorDiagnostics(floorId, timeout?)` |
|
||
| **/engine/ 支持** | ✅ |
|
||
| **最低版本** | 2.3.0 |
|
||
|
||
**请求 payload**:
|
||
```ts
|
||
{
|
||
floorId?: string | number // 目标楼层 ID，默认当前楼层
|
||
}
|
||
```
|
||
|
||
**成功响应**:
|
||
```ts
|
||
{
|
||
success: true,
|
||
floorId: string | number,
|
||
floorCode: string,
|
||
floorName: string,
|
||
status: "OK" | "WARN" | "ERROR",
|
||
modelReady: boolean,
|
||
poiCount: number,
|
||
spaceCount: number,
|
||
guideStopCount: number,
|
||
navigablePlaceCount: number,
|
||
routeNodeCount: number,
|
||
routeEdgeCount: number,
|
||
routePlanningReady: boolean,
|
||
warnings: string[]
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```ts
|
||
{
|
||
success: false
|
||
}
|
||
// error:
|
||
{
|
||
code: "ERR_INVALID_PARAMS", // floorId 为空时
|
||
message: "floorId 不能为空"
|
||
}
|
||
// 或
|
||
{
|
||
code: "ERR_NETWORK" | "ERR_FAILED",
|
||
message: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 基座主动事件一览
|
||
|
||
以下事件由基座通过 `SGS_MAP_EVENT` 类型主动推送，无需 SDK 请求：
|
||
|
||
| 事件 action | 触发时机 | payload 关键字段 |
|
||
|-------------|---------|-----------------|
|
||
| `ENGINE_READY` | 引擎初始化完成 / HELLO 响应 | `engineVersion`, `protocolVersion`, `sdkVersion`, `floorId`, `poiCount`, `hasRouteNetwork` |
|
||
| `ON_MODEL_LOADING` | 模型开始加载 | `floorId`, `modelUrl` |
|
||
| `ON_MODEL_READY` | 模型解析完成 | `floorId`, `parseTimeMs` |
|
||
| `ON_MODEL_ERROR` | 模型加载失败/超时 | `floorId`, `error`, `fallbackUsed` |
|
||
| `ON_FLOOR_BUNDLE_READY` | 楼层 bundle 数据加载完成 | `floorId`, `dataVersion` |
|
||
| `ON_POI_CLICK` | 用户点击 POI | `id`, `name`, `type`, `floorId` |
|
||
| `ON_ROUTE_TRANSFER` | 跨楼层换乘提示 | `currentFloorId`, `targetFloorId`, `transferType` |
|
||
|
||
---
|
||
|
||
## 错误码汇总
|
||
|
||
| 错误码 | 说明 | 出现指令 |
|
||
|--------|------|---------|
|
||
| `ERR_INVALID_MODE` | `SET_VIEW_MODE` 参数非法 | SET_VIEW_MODE |
|
||
| `ERR_INVALID_PARAMS` | 必填参数缺失或无效 | PLAN_ROUTE, GET_GUIDE_STOPS_BY_HALL, GET_NAVIGABLE_PLACES, PRELOAD_FLOOR, GET_FLOOR_DIAGNOSTICS |
|
||
| `ERR_ROUTING_FAILED` | NavMesh 路径规划失败 | PLAN_ROUTE |
|
||
| `ERR_NETWORK` | 后端 API 网络异常 | GET_MANIFEST, LOAD_FLOOR_BUNDLE, GET_NAVIGABLE_PLACES, PRELOAD_FLOOR, GET_DIAGNOSTICS, GET_FLOOR_DIAGNOSTICS |
|
||
| `ERR_FAILED` | 通用失败 | 多个异步指令的 catch 兜底 |
|
||
| `ERR_UNSUPPORTED` | 基座不支持该指令 | 未识别的 action（default 分支）、mock-release 专用指令在非 mock 模式下调用 |
|
||
|
||
---
|
||
|
||
## 版本演进
|
||
|
||
| 版本 | 新增 action |
|
||
|------|------------|
|
||
| 1.0.0 | HELLO, CHANGE_FLOOR, FOCUS_TO, ADD_MARKER, ADD_BUSINESS_MARKER, REMOVE_MARKER, REMOVE_BUSINESS_MARKER, CLEAR_MARKERS, PLAN_ROUTE, HIGHLIGHT_POLYGON, CLEAR_ROUTE, RESET_VIEW, GET_STATE, GET_POIS |
|
||
| 1.5.0 | TOGGLE_LAYER, SET_VISIBLE_TYPES |
|
||
| 2.1.0 | GET_MANIFEST, LOAD_FLOOR_BUNDLE, GET_FLOOR_POIS, GET_SPACES, GET_GUIDE_STOPS, GET_GUIDE_STOPS_BY_HALL, PRELOAD_FLOOR, CLEAR_MODEL_CACHE, GET_PERFORMANCE_STATS |
|
||
| 2.3.0 | SET_VIEW_MODE, GET_NAVIGABLE_PLACES, GET_DIAGNOSTICS, GET_FLOOR_DIAGNOSTICS |
|