Files

lyf 7cda427de9 修复 SGS SDK 导览数据源与模型加载

升级 SDK API 数据契约，补齐 guideStops、业务 POI、诊断与路线数据接口。

修复 SDK 模式下 POI/模型/楼层混用静态数据的问题，并为 ThreeMap 模型加载增加短退避重试。

2026-07-02 10:26:52 +08:00

SGS Map SDK Changelog

[2.4.0] - 2026-06-27

业务 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 指向任意数据服务地址，彻底解耦。

解耦 Next.js 依赖：底座引擎完全脱离 Next.js / Zustand 等大体积依赖，精简为极速加载的原生单页应用（Vite + React）。
优化发包构建管线：重新梳理 package.json scripts，将 SDK Bridge 与 SDK Engine 打包构建命令在命令行端进行解耦和串联（npm run build:sdk），优化了 scripts/copy-sdk.js 拷贝管线，避免嵌套与死循环构建。
演示 Demo 改造：修改 SDK 官方 Demo 的 app.js 使其默认消费静态 ../engine/index.html 渲染底座，并开启 server 参数透传及 targetOrigin: '*' 确权广播，实现宿主与静态底座零配置无缝通信。

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，提供清晰的健康状态指示

修复阻断问题：Manifest 正常流程补齐 v2.3 capabilities 字段设置，修复所有新增字段返回 null 的问题
楼层级统计准确性修复：修复楼层诊断中 guideStopCount 缺少 floorId 过滤，现在正确按楼层统计而非全馆统计
地图级 summary 完善：补齐地图级诊断 summary 的 4 个统计项（modelReadyFloorCount, poiCount, spaceCount, guideStopCount），现在包含完整的 8 个统计维度
H5 Bridge 消息处理：新增 GET_DIAGNOSTICS 和 GET_FLOOR_DIAGNOSTICS 消息处理，完整支持诊断功能

性能监控与埋点治理：新增底层加载耗时记录（如 sdkCreatedAt, iframeDomReadyMs, engineReadyMs, manifestLoadMs, modelDownloadAndParseMs），提供完整的控制台性能概览面板。
Demo 全面重构：Kiosk Demo 与 Mobile Demo 引入非阻塞型 Loading 遮罩层，提升了白屏阶段的 UI 可交互体验。

SDK 发布管线加固：构建体系重构，每次 Build 将自动清空并同步覆盖 public/sdk/ 与发版包中的产物，修正了 Source Map 的内部指向错误，彻底杜绝了旧类型定义的残留。
深度清理所有旧版硬编码版本号注释，统一向 v2.2.0 API 规范拉齐。
对齐了前后端 SDK Payload 返回值 VO 定义。

双域双向通信架构：采用不可见 iframe 挂载基座，通过安全沙箱和 postMessage 握手进行通信，从源头上解决 WebGL Context 内存泄漏和生命周期挂起问题。
动态点位系统 (Markers API)：新增 addMarker / removeMarker / clearMarkers 接口，支持锚定三维节点（防模型漂移）和绝对坐标系定位。
异步寻路确权系统：planRoute 和 changeFloor 升级为基于 requestId 的 Promise 异步确权模式，支持 Timeout 拦截机制。
高精模型与坐标系重构：全面接入米级统一坐标系（废弃 CAD 毫米系），支持多楼层分层物理拆分加载。