更新 SGS 地图 SDK 并补充数据层接入手册

static/sgs-map-sdk/sdk-protocol.md

@@ -1,6 +1,6 @@
 # SGS Map SDK 通信协议规格 (Protocol Specification)
 
-> 版本: V2.0.0
+> 版本: V2.3.0
 > 适用对象: SGS Map SDK 核心开发者、渲染基座 (h5-sdk) 开发者
 
 本文档定义了外壳 SDK (`sgs-map-sdk.js`) 与 独立渲染基座 iframe (`h5-sdk/page.tsx`) 之间的 `postMessage` 通信契约。所有消息传递必须严格遵循此结构，以保障多域环境下的确权、安全过滤与异步生命周期追踪。
@@ -61,7 +61,7 @@ sequenceDiagram
     
     Note over SDK,Base: 此时 HTML 刚加载，WebGL/GLB 模型并未解析完成
     
-    SDK->>Base: 发送 HELLO { protocolVersion: 2, sdkVersion: "2.0.0" }
+    SDK->>Base: 发送 HELLO { protocolVersion: 2, sdkVersion: "2.3.0" }
     Base->>Base: 挂载 WebGL，拉取 GLB 及 POI 接口
     Base-->>SDK: 内部加载完毕，推送 ENGINE_READY 事件
     SDK->>SDK: 解锁 isReady = true，清空缓存命令队列
@@ -88,9 +88,24 @@ sequenceDiagram
 | `RESET_VIEW` | (空) | `{ success: true }` | 重置相机视角至初始状态 |
 | `SET_VIEW_MODE` | `{ mode: '2d' | '3d' }` | `{ success: true }` | 切换 2D/3D 视角模式 |
 | `TOGGLE_LAYER` | `{ types: string[], visible: boolean }` | `{ success: true, visibleTypes: string[] }` | 批量控制某类底座设施的显示隐藏 |
+| `GET_MANIFEST` | `{}` | `ManifestData` | 获取地图 Manifest（楼层列表、元数据） |
+| `LOAD_FLOOR_BUNDLE` | `{ floorId: string \| number }` | `FloorBundleData` | 一次性加载楼层完整 Bundle（模型+POI+空间面+讲解点） |
+| `GET_FLOOR_POIS` | `{ floorId: string \| number }` | `{ pois: PoiItem[] }` | 获取指定楼层 POI 列表 |
+| `GET_SPACES` | `{ floorId: string \| number }` | `{ spaces: SpaceItem[] }` | 获取指定楼层空间面列表 |
+| `GET_GUIDE_STOPS` | `{ floorId: string \| number }` | `{ guideStops: GuideStopItem[] }` | 获取指定楼层讲解点列表 |
+| `GET_NAVIGABLE_PLACES` | `{ floorId: string \| number }` | `{ navigablePlaces: SgsNavigablePlace[] }` | 获取指定楼层可导航目的地列表 |
+| `PRELOAD_FLOOR` | `{ floorId: string \| number }` | `{ success: true }` | 后台静默预加载指定楼层模型资源 |
+| `CLEAR_MODEL_CACHE` | (空) | `{ success: true, freedBytes: number }` | 清空客户端模型缓存 |
+| `GET_PERFORMANCE_STATS` | (空) | `PerformanceStats` | 获取渲染性能统计（FPS/DrawCall/纹理内存） |
+| `GET_DIAGNOSTICS` | `{}` | `SgsMapDiagnostics` | 获取地图级 SDK 数据健康诊断 |
+| `GET_FLOOR_DIAGNOSTICS` | `{ floorId: string \| number }` | `SgsFloorDiagnostics` | 获取指定楼层 SDK 数据健康诊断 |
 
 > **类型定义备注：**
 > `SgsMapNode` 及 `RouteResult` 的精确结构请参考 TypeScript 源码定义：`sdk-src/types.ts`。
+>
+> **v2.3.0 类型放宽**：所有 ID 字段（`floorId`、`mapId`、`poiId` 等）支持 `string | number`，向下兼容纯数字调用。
+>
+> **v2.3.0 主要类型**：`ManifestData`、`FloorBundleData`、`PoiItem`、`SpaceItem`、`GuideStopItem`、`SgsNavigablePlace`、`SgsMapDiagnostics`、`SgsFloorDiagnostics`、`PerformanceStats` 的精确结构请参考 `sdk-src/types.ts`。
 
 ---
 
@@ -101,6 +116,11 @@ sequenceDiagram
 | `ENGINE_READY` | `{ engineVersion, protocolVersion, sdkVersion }` | `ready` | 基座完全挂载，WebGL 画布可渲染 |
 | `ON_POI_CLICK` | `{ id, name, type }` | `poiClick` | 用户在触摸屏或鼠标点击了高亮要素 |
 | `ON_FLOOR_CHANGED`| `{ floorId }` | `floorChanged` | 楼层完全切换完毕后自动抛出 |
+| `ON_MODEL_LOADING` | `{ floorId, modelUrl }` | `modelLoading` | 模型文件开始网络加载 |
+| `ON_MODEL_READY` | `{ floorId, parseTimeMs }` | `modelReady` | 模型解析完成，Scene 已挂载 |
+| `ON_MODEL_ERROR` | `{ floorId, error, fallbackUsed }` | `modelError` | 模型加载失败（含 fallback 信息） |
+| `ON_FLOOR_BUNDLE_READY` | `{ floorId, dataVersion }` | `floorBundleReady` | 楼层 Bundle 数据全部就绪 |
+| `ON_ROUTE_READY` | `{ routeId, distance, duration }` | `routeReady` | 路径规划完成 |
 
 ---