7.0 KiB
7.0 KiB
SGS Map SDK Changelog
[2.4.1] - 2026-07-01
Phase 2: 高层导航API (2026-07-01)
新增功能
- POI间导航API：新增
planRouteToPoi和planRouteBetweenPois方法，支持直接通过POI ID完成导航 - 后端能力扩展：新增
/routes/plan-to-poi和/routes/plan-between-pois接口，自动查询POI坐标 - Manifest能力声明：新增
routeToPoi、routeDiagnostics、sdkRuntimeCache能力字段 - 错误码标准化：新增路线规划专用错误码（1009012000段），提供友好的错误提示
Phase 1: 导航稳定性修复
Bug Fixes
- P0-1: Fixed same-floor route not rendering in Handoff mode (currentFloorPointsArray was dead code)
- P0-2: Fixed CLEAR_ROUTE incomplete state cleanup (10 states now fully reset)
- Fixed route overlay when planning consecutive routes
Improvements
- Added ON_ROUTE_READY event dispatch after successful PLAN_ROUTE
- Added preferElevator option to RouteOptions
- SDK version bumped to 2.4.1
[2.4.0] - 2026-06-27
🚀 新特性 (New Features)
- 业务 POI 接口与扩展机制：新增
getBusinessPois获取商户级业务 POI，新增queryPois支持按地图、楼层、分组、类型、关键词进行组合查询，实现与底层空间基础设施数据解耦。 - 特色动线查询与展示：新增
getFeaturedRoutes/getFeaturedRoute接口获取馆方精选路线，新增showFlowline/clearFlowline接口提供跨层全局鸟瞰特色动线展示功能。 - 独立 H5 渲染引擎包 (SDK Engine)：新增
sdk-engine/独立打包构建目录，支持静态编译输出至静态engine/目录。底座不依赖 Next.js 前端路由及 hydration 状态限制，由宿主系统通过 iframe 挂载../engine/index.html独立运行。 - 配置与数据解耦：底座数据服务入口由
server查询参数动态指定，静态部署后可通过?server=http://localhost:3001指向任意数据服务地址，彻底解耦。
🐞 修复与强化 (Fixes & Improvements)
- 解耦 Next.js 依赖：底座引擎完全脱离 Next.js / Zustand 等大体积依赖，精简为极速加载的原生单页应用（Vite + React）。
- 优化发包构建管线：重新梳理
package.jsonscripts，将 SDK Bridge 与 SDK Engine 打包构建命令在命令行端进行解耦和串联（npm run build:sdk），优化了scripts/copy-sdk.js拷贝管线，避免嵌套与死循环构建。 - 演示 Demo 改造：修改 SDK 官方 Demo 的
app.js使其默认消费静态../engine/index.html渲染底座，并开启server参数透传及targetOrigin: '*'确权广播，实现宿主与静态底座零配置无缝通信。
[2.3.0] - 2026-06-23
🚀 新特性 (New Features)
- Manifest Capabilities 扩展：新增 9 个 v2.3 标准能力字段（
mapLoading,floorSwitching,poiQuery,spaceQuery,navigablePlaces,crossFloorRoute,accessibleRoute,highlight,diagnostics），前端可按需判断后端支持的功能。 - 诊断接口 (Diagnostics API)：新增地图级和楼层级诊断接口，实时检查数据完整性和就绪状态：
sdk.getDiagnostics()- 获取地图整体诊断信息（包含所有楼层摘要和汇总统计）sdk.getFloorDiagnostics(floorId)- 获取单个楼层的详细诊断信息- 诊断信息包含：模型就绪状态、POI数量、空间面数量、讲解点数量、可导航目的地数量、路网节点/边数量、路径规划就绪状态、警告列表
- 统一状态枚举：诊断接口状态统一为
OK/WARN/ERROR，提供清晰的健康状态指示
🐞 修复与强化 (Fixes & Improvements)
- 修复阻断问题：Manifest 正常流程补齐 v2.3 capabilities 字段设置，修复所有新增字段返回 null 的问题
- 楼层级统计准确性修复：修复楼层诊断中
guideStopCount缺少floorId过滤，现在正确按楼层统计而非全馆统计 - 地图级 summary 完善：补齐地图级诊断 summary 的 4 个统计项（
modelReadyFloorCount,poiCount,spaceCount,guideStopCount），现在包含完整的 8 个统计维度 - H5 Bridge 消息处理：新增
GET_DIAGNOSTICS和GET_FLOOR_DIAGNOSTICS消息处理，完整支持诊断功能
📝 类型定义更新
- 新增
SgsMapDiagnostics接口（地图级诊断响应） - 新增
SgsFloorDiagnostics接口（楼层级诊断响应） - 新增
SgsFloorDiagnosticsSummary接口（楼层诊断摘要） - 扩展
SgsSdkManifest.capabilities类型定义，包含所有 v2.3 标准字段
🔧 后端接口新增
GET /app-api/gis/sdk/maps/{mapId}/diagnostics- 地图级诊断GET /app-api/gis/sdk/floors/{floorId}/diagnostics- 楼层级诊断
[2.2.0] - 2026-06-19
🚀 新特性 (New Features)
- 性能监控与埋点治理：新增底层加载耗时记录（如
sdkCreatedAt,iframeDomReadyMs,engineReadyMs,manifestLoadMs,modelDownloadAndParseMs），提供完整的控制台性能概览面板。 - Demo 全面重构：Kiosk Demo 与 Mobile Demo 引入非阻塞型 Loading 遮罩层，提升了白屏阶段的 UI 可交互体验。
🐞 修复与强化 (Fixes & Improvements)
- SDK 发布管线加固：构建体系重构，每次 Build 将自动清空并同步覆盖
public/sdk/与发版包中的产物，修正了 Source Map 的内部指向错误，彻底杜绝了旧类型定义的残留。 - 深度清理所有旧版硬编码版本号注释，统一向 v2.2.0 API 规范拉齐。
- 对齐了前后端 SDK Payload 返回值 VO 定义。
[2.0.0] - 2026-06-12
🚀 新特性 (New Features)
- 双域双向通信架构：采用不可见 iframe 挂载基座，通过安全沙箱和
postMessage握手进行通信，从源头上解决 WebGL Context 内存泄漏和生命周期挂起问题。 - 动态点位系统 (Markers API)：新增
addMarker/removeMarker/clearMarkers接口，支持锚定三维节点（防模型漂移）和绝对坐标系定位。 - 异步寻路确权系统：
planRoute和changeFloor升级为基于requestId的 Promise 异步确权模式，支持 Timeout 拦截机制。 - 高精模型与坐标系重构：全面接入米级统一坐标系（废弃 CAD 毫米系），支持多楼层分层物理拆分加载。
🐞 修复与强化 (Fixes & Improvements)
HELLLO与ENGINE_READY双向握手协议对齐。targetOrigin自动推导增强，严格拦截非法的跨域源消息，免疫跨站攻击。- SDK Iframe 生命周期的
onerror捕捉增强，能正确派发loadError事件。 - 补齐了丢失的
floorChanged运行时事件透传。 - 完善
package.json工程化暴露，同时提供 IIFE 与 ESM 产物，开启源码映射（SourceMap）。 addMarker接口强制引入强类型定义MarkerConfig。
🗑️ 废弃与移除 (Deprecations)
- 彻底移除半成品接口
startNavigateAnim/stopNavigateAnim。 - 彻底移除废弃接口
addBusinessMarker/removeBusinessMarker，统一收编为addMarker。