升级 SGS 地图 SDK 至 2.4.1

2026-07-13 11:00:04 +08:00
parent 8e187d6d4f
commit e473b6a2a5
18 changed files with 1655 additions and 25 deletions
--- a/.env.development
+++ b/.env.development
@@ -15,7 +15,7 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
 VITE_SGS_H5_ENGINE_URL=/h5-sdk
 VITE_SGS_SDK_ORIGIN=
 VITE_SGS_SDK_TIMEOUT_MS=15000
--- a/.env.example
+++ b/.env.example
@@ -14,7 +14,7 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
 VITE_SGS_H5_ENGINE_URL=/h5-sdk
 VITE_SGS_SDK_ORIGIN=
 VITE_SGS_SDK_TIMEOUT_MS=15000
--- a/.env.production
+++ b/.env.production
@@ -14,7 +14,7 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
 VITE_SGS_H5_ENGINE_URL=/h5-sdk
 VITE_SGS_SDK_ORIGIN=https://guide.sznhmuseum.org.cn
 VITE_SGS_SDK_TIMEOUT_MS=15000
--- a/.env.test
+++ b/.env.test
@@ -14,7 +14,7 @@ VITE_AUDIO_API_BASE_URL=/app-api
 VITE_AUDIO_LANGUAGE=zh-CN
 VITE_SGS_API_BASE_URL=/app-api
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
 VITE_SGS_H5_ENGINE_URL=/h5-sdk
 VITE_SGS_SDK_ORIGIN=https://guide.whaoyue.com
 VITE_SGS_SDK_TIMEOUT_MS=15000
--- a/README.md
+++ b/README.md
@@ -129,7 +129,7 @@ VITE_AUDIO_LANGUAGE=zh-CN

 # SGS SDK/H5 地图基座配置；当前代码尚未把 SDK renderer 接入页面渲染
 VITE_SGS_MAP_ID=1
-VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js
+VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js?v=2.4.1
 VITE_SGS_H5_ENGINE_URL=/h5-sdk
 VITE_SGS_SDK_ORIGIN=
 VITE_SGS_SDK_TIMEOUT_MS=5000
--- a/src/config/dataSource.ts
+++ b/src/config/dataSource.ts
@@ -3,7 +3,7 @@ export type GuideContentDataSourceMode = 'static' | 'remote' | 'mock'

 const allowedModes = new Set<DataSourceMode>(['static', 'api', 'sdk'])
 const allowedGuideContentModes = new Set<GuideContentDataSourceMode>(['static', 'remote', 'mock'])
-const defaultSdkScriptUrl = '/static/sgs-map-sdk/index.global.js'
+const defaultSdkScriptUrl = '/static/sgs-map-sdk/index.global.js?v=2.4.1'
 const defaultSgsEngineUrl = '/h5-sdk'
 const defaultSdkTimeoutMs = 5000
 const defaultApiBaseUrl = '/app-api'
--- a/src/services/sgs/SgsMapService.ts
+++ b/src/services/sgs/SgsMapService.ts
@@ -3,6 +3,7 @@ import type {
  SgsMapSDKInstance,
  SgsMarkerConfig,
  SgsMapNode,
+  SgsRouteOptions,
  SgsRouteResult
 } from '@/types/sgs-map-sdk'
 import {
@@ -116,9 +117,9 @@ export class SgsMapService {
    return this.sdk
  }

-  async changeFloor(floorId: string | number) {
+  async changeFloor(floorId: string | number, options?: { forceReload?: boolean }) {
    const sdk = await this.getReadySdk()
-    return sdk.changeFloor(floorId, this.options.timeout)
+    return sdk.changeFloor(floorId, this.options.timeout, options)
  }

  async focusTo(node: SgsMapNode | string) {
@@ -138,15 +139,15 @@ export class SgsMapService {

  async resetView() {
    const sdk = await this.getReadySdk()
-    sdk.resetView()
+    return sdk.resetView(this.options.timeout)
  }

  async setViewMode(mode: '2d' | '3d') {
    const sdk = await this.getReadySdk()
-    sdk.setViewMode(mode)
+    return sdk.setViewMode(mode, this.options.timeout)
  }

-  async planRoute(from: SgsMapNode | string, to: SgsMapNode | string, options?: unknown): Promise<SgsRouteResult> {
+  async planRoute(from: SgsMapNode | string, to: SgsMapNode | string, options?: SgsRouteOptions): Promise<SgsRouteResult> {
    const sdk = await this.getReadySdk()
    return sdk.planRoute(from, to, options, this.options.timeout)
  }
--- a/src/types/sgs-map-sdk.ts
+++ b/src/types/sgs-map-sdk.ts
@@ -24,6 +24,20 @@ export interface SgsRouteResult {
  segments?: SgsRouteSegment[]
 }

+export interface SgsRouteOptions {
+  mode?: 'walk' | 'accessible'
+  wheelchair?: boolean
+  preferElevator?: boolean
+}
+
+export interface SgsSdkRoutePoint {
+  poiId?: string | number
+  floorId?: string | number
+  x?: number
+  y?: number
+  z?: number
+}
+
 export interface SgsMapSDKOptions {
  container: string | HTMLElement
  sdkUrl?: string
@@ -37,6 +51,13 @@ export interface SgsMapSDKOptions {
 export interface SgsMapEvents {
  ready: { engineVersion: string; protocolVersion: number }
  poiClick: { id: string | number; poiId?: string | number; name: string; type: string; floorId?: string | number; description?: string }
+  poiDetail: SgsPoi & Record<string, unknown>
+  poiNavigate: SgsPoi & Record<string, unknown>
+  poiClose: Record<string, unknown>
+  spaceClick: SgsSpaceArea & Record<string, unknown>
+  spaceDetail: SgsSpaceArea & Record<string, unknown>
+  spaceNavigate: SgsSpaceArea & Record<string, unknown>
+  spaceClose: Record<string, unknown>
  floorChanged: { floorId: string | number }
  error: { code: string; message: string }
  loadError: { type: string; detail: string }
@@ -57,6 +78,8 @@ export interface SgsMapEvents {
  modelError: { floorId: string | number; error: string; fallbackUsed: boolean }
  floorBundleReady: { floorId: string | number; dataVersion: string }
  routeReady: { routeId: string; distance: number; duration: number; segmentCount?: number; hasTransfer?: boolean }
+  roamingProgress: { progress: number }
+  roamingDone: { success: boolean }
 }

 export type SgsRouteTransferType = 'ELEVATOR' | 'STAIRS' | 'ESCALATOR'
@@ -95,14 +118,20 @@ export interface SgsMapSDKInstance {
  whenReady(): Promise<unknown>
  ready(): Promise<unknown>
  focusTo(node: SgsMapNode | string): void
-  changeFloor(floorId: string | number, timeout?: number): Promise<{ success: boolean; floorId: string | number }>
+  changeFloor(floorId: string | number, timeout?: number, options?: { forceReload?: boolean }): Promise<{ success: boolean; floorId: string | number }>
  addMarker(config: SgsMarkerConfig): void
  removeMarker(markerId: string): void
  clearMarkers(): void
  highlightPolygon(payload: string | object): void
-  planRoute(from: SgsMapNode | string, to: SgsMapNode | string, options?: unknown, timeout?: number): Promise<SgsRouteResult>
-  planRouteV2(from: SgsMapNode, to: SgsMapNode, options?: unknown, timeout?: number): Promise<SgsRouteResult>
+  planRoute(from: SgsMapNode | string, to: SgsMapNode | string, options?: SgsRouteOptions, timeout?: number): Promise<SgsRouteResult>
+  planRouteV2(from: SgsMapNode, to: SgsMapNode, options?: SgsRouteOptions, timeout?: number): Promise<SgsRouteResult>
  clearRoute(): void
+  renderRoutePoints(pathPoints: Array<{ x: number; y: number; z: number }>, options?: unknown, timeout?: number): Promise<SgsRouteResult>
+  startRoaming(pathPoints?: Array<{ x: number; y: number; z: number }>, options?: SgsRouteRoamingOptions, timeout?: number): Promise<{ success: boolean; mode?: string }>
+  stopRoaming(timeout?: number): Promise<{ success: boolean }>
+  toggleRoamingPause(timeout?: number): Promise<{ success: boolean; paused?: boolean }>
+  planRouteToPoi(from: string | number | SgsSdkRoutePoint, toPoiId: string | number, options?: SgsRouteOptions, timeout?: number): Promise<SgsRouteResult>
+  planRouteBetweenPois(fromPoiId: string | number, toPoiId: string | number, options?: SgsRouteOptions, timeout?: number): Promise<SgsRouteResult>
  getState(): Promise<unknown>
  resetView(timeout?: number): Promise<{ success: boolean }>
  setViewMode(mode: '2d' | '3d', timeout?: number): Promise<{ success: boolean; mode: string }>
@@ -126,6 +155,7 @@ export interface SgsMapSDKInstance {
  queryPois(params: SgsPoiQueryParams, timeout?: number): Promise<SgsPoi[]>
  getFeaturedRoutes(mapId?: string | number, options?: { limit?: number }, timeout?: number): Promise<SgsFeaturedRouteSummary[]>
  getFeaturedRoute(routeId: string | number, timeout?: number): Promise<SgsFeaturedRouteDetail>
+  planFeaturedRoutePreview(payload: SgsFeaturedRoutePreviewPayload, timeout?: number): Promise<SgsRouteResult>
  showFlowline(routeId: string | number, options?: SgsFlowlineOptions, timeout?: number): Promise<{ success: boolean; routeId: string | number }>
  clearFlowline(): void
  destroy(): void
@@ -162,10 +192,15 @@ export interface SgsPoi {
  status: 'ACTIVE' | 'INACTIVE'
  anchorNodeName?: string | null
  description?: string
+  descriptionEn?: string
+  extParams?: string | Record<string, unknown>
  iconUrl?: string
  poiGroup?: SgsPoiGroup
  businessType?: SgsBusinessPoiType
  coverImageUrl?: string | null
+  images?: string | string[] | null
+  externalUrl?: string | null
+  videoUrl?: string | null
  phone?: string | null
  businessHours?: string | null
  sortOrder?: number | null
@@ -182,7 +217,22 @@ export interface SgsSdkManifest {
  updatedAt: string
  coordinateSystem: string
  floors: SgsSdkFloorSummary[]
-  capabilities: Record<string, boolean | undefined>
+  routeAssets?: SgsRouteAsset[]
+  capabilities: Record<string, boolean | undefined> & { sameGroundCompositeRoute?: boolean }
+}
+
+export interface SgsRouteAsset {
+  id: string | number
+  mapId?: string | number
+  floorId?: string | number | null
+  floorCode?: string | null
+  assetRole: string
+  modelUrl: string
+  sourceFileName?: string | null
+  sourceNodeName?: string | null
+  modelVersion?: string | null
+  coverageFloorCodes?: string[]
+  sortOrder?: number
 }

 export interface SgsSdkFloorSummary {
@@ -222,13 +272,26 @@ export interface SgsFloorBundle {
 export interface SgsSpaceArea {
  id: string | number
  name: string
+  displayName?: string
  type: string
+  typeName?: string
  floorId: string | number
+  floorCode?: string
  boundaryWkt: string
-  center: { x: number; y: number; z: number }
+  center: { x: number; y?: number; z: number; radius?: number }
  sourceNodeName?: string
  status: 'ACTIVE' | 'INACTIVE'
  colorHex?: string
+  description?: string | null
+  descriptionEn?: string | null
+  coverImageUrl?: string | null
+  images?: string | string[] | null
+  galleryUrls?: string | string[] | null
+  videoUrl?: string | null
+  externalUrl?: string | null
+  openTime?: string | null
+  exhibitCount?: number | null
+  areaSqm?: number | null
 }

 export interface SgsGuideStop {
@@ -268,6 +331,11 @@ export interface SgsNavigablePlace {
  x: number
  z: number
  nodeId?: string | number
+  routeNodeId?: string | number
+  sourceType?: 'POI' | 'SPACE' | 'FLOOR' | 'CUSTOM' | string | null
+  sourceId?: string | number | null
+  anchorId?: string | number | null
+  anchorType?: string | null
  ownerName?: string
  typeCode?: string
  typeName?: string
@@ -305,6 +373,8 @@ export interface SgsPerformanceStats {
  routePlanMs?: number
  dracoUsed?: boolean
  fallbackUsed?: boolean
+  bundleCacheHit?: boolean
+  currentModelUrl?: string
  currentFloorId?: string | number
 }

@@ -394,6 +464,21 @@ export interface SgsFeaturedRouteDetail extends SgsFeaturedRouteSummary {
  waypoints: SgsFeaturedRouteWaypoint[]
 }

+export interface SgsFeaturedRoutePreviewPayload {
+  routeId?: string | number
+  routeName?: string
+  color?: string | null
+  routeColor?: string | null
+  startEntrance?: SgsRouteEndpoint | null
+  endEntrance?: SgsRouteEndpoint | null
+  waypoints?: SgsFeaturedRouteWaypoint[]
+}
+
+export interface SgsRouteRoamingOptions {
+  mode?: 'third-person' | 'top'
+  speed?: number
+}
+
 export interface SgsFlowlineOptions {
  autoFit?: boolean
  showLabels?: boolean
--- a/static/sgs-map-sdk/CHANGELOG.md
+++ b/static/sgs-map-sdk/CHANGELOG.md
@@ -1,5 +1,29 @@
 # 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)
--- a/static/sgs-map-sdk/index.d.mts
+++ b/static/sgs-map-sdk/index.d.mts
--- a/static/sgs-map-sdk/index.d.ts
+++ b/static/sgs-map-sdk/index.d.ts
@@ -73,6 +73,21 @@ interface RouteResult {
 interface RouteOptions {
    mode?: 'walk' | 'accessible';
    wheelchair?: boolean;
+    /** v2.4.1: 跨楼层时优先选择电梯 */
+    preferElevator?: boolean;
+}
+/** SDK 2.4.1: 路线起点/终点定义 */
+interface SdkRoutePoint {
+    /** POI ID（POI模式） */
+    poiId?: string | number;
+    /** 楼层 ID（坐标模式） */
+    floorId?: string | number;
+    /** X坐标（GLB米，坐标模式） */
+    x?: number;
+    /** Y坐标（GLB米，坐标模式） */
+    y?: number;
+    /** Z坐标（GLB米，可选） */
+    z?: number;
 }
 /** SDK 初始化配置 */
 interface SGSMapSDKOptions {
@@ -101,6 +116,13 @@ interface SGSMapEvents {
        floorId?: string | number;
        description?: string;
    };
+    poiDetail: SgsPoi & Record<string, unknown>;
+    poiNavigate: SgsPoi & Record<string, unknown>;
+    poiClose: Record<string, unknown>;
+    spaceClick: SgsSpaceArea & Record<string, unknown>;
+    spaceDetail: SgsSpaceArea & Record<string, unknown>;
+    spaceNavigate: SgsSpaceArea & Record<string, unknown>;
+    spaceClose: Record<string, unknown>;
    floorChanged: {
        floorId: string | number;
    };
@@ -153,6 +175,14 @@ interface SGSMapEvents {
        segmentCount?: number;
        hasTransfer?: boolean;
    };
+    /** 路径漫游进度，progress 范围 0-1 */
+    roamingProgress: {
+        progress: number;
+    };
+    /** 路径漫游结束 */
+    roamingDone: {
+        success: boolean;
+    };
 }
 /** SDK 错误码 */
 type SGSErrorCode = 'ERR_TIMEOUT' | 'ERR_NO_PATH' | 'ERR_FLOOR_NOT_FOUND' | 'ERR_NOT_READY' | 'ERR_POI_NOT_FOUND' | 'ERR_NETWORK' | 'ERR_IFRAME_DEAD' | 'ERR_UNAUTHORIZED' | 'ERR_UNSUPPORTED' | 'ERR_FAILED' | 'ERR_DESTROYED' | 'ERR_IFRAME_LOAD' | 'ERR_READY_TIMEOUT';
@@ -274,12 +304,19 @@ interface SgsPoi {
    anchorNodeName?: string | null;
    /** 描述 */
    description?: string;
+    /** 英文描述 */
+    descriptionEn?: string;
+    /** 扩展参数 JSON */
+    extParams?: string | Record<string, unknown>;
    /** 图标 URL */
    iconUrl?: string;
    floorId?: string | number;
    poiGroup?: SgsPoiGroup;
    businessType?: SgsBusinessPoiType | string;
    coverImageUrl?: string | null;
+    images?: string | string[] | null;
+    externalUrl?: string | null;
+    videoUrl?: string | null;
    phone?: string | null;
    businessHours?: string | null;
    sortOrder?: number | null;
@@ -360,6 +397,8 @@ interface SgsSdkManifest {
    coordinateSystem: string;
    /** 楼层摘要列表（按 sortOrder 升序） */
    floors: SgsSdkFloorSummary[];
+    /** 路线显示资产列表，如 EXTERIOR + L1 同地面组合模型 */
+    routeAssets?: SgsRouteAsset[];
    /** 能力声明 */
    capabilities: {
        /** 是否支持 Draco 压缩模型 */
@@ -392,8 +431,34 @@ interface SgsSdkManifest {
        poiSearch?: boolean;
        featuredRoutes?: boolean;
        flowlinePreview?: boolean;
+        sameGroundCompositeRoute?: boolean;
    };
 }
+/** v2.4.1 路线显示资产 */
+interface SgsRouteAsset {
+    /** 资产 ID */
+    id: string | number;
+    /** 地图 ID */
+    mapId?: string | number;
+    /** 资产所属楼层 ID；全局资产可为空 */
+    floorId?: string | number | null;
+    /** 资产楼层编码或组合编码 */
+    floorCode?: string | null;
+    /** 资产角色，如 SAME_GROUND_COMPOSITE */
+    assetRole: string;
+    /** 模型 URL */
+    modelUrl: string;
+    /** 源文件名 */
+    sourceFileName?: string | null;
+    /** 源节点名 */
+    sourceNodeName?: string | null;
+    /** 模型版本标签 */
+    modelVersion?: string | null;
+    /** 组合资产覆盖的楼层编码，如 ["EXTERIOR", "L1"] */
+    coverageFloorCodes?: string[];
+    /** 排序 */
+    sortOrder?: number;
+}
 /** v2.2.0 楼层摘要（manifest 内嵌） */
 interface SgsSdkFloorSummary {
    /** 楼层 ID */
@@ -468,17 +533,24 @@ interface SgsSpaceArea {
    id: string | number;
    /** 显示名称 */
    name: string;
+    /** 展示名称（兼容 SDK 内部空间标签） */
+    displayName?: string;
    /** 空间类型（如 exhibition_hall / corridor / office） */
    type: string;
+    /** 空间类型中文名 */
+    typeName?: string;
    /** 所属楼层 ID */
    floorId: string | number;
+    /** 所属楼层编码 */
+    floorCode?: string;
    /** WKT 边界多边形 */
    boundaryWkt: string;
    /** 中心点 GLB 坐标（米） */
    center: {
        x: number;
-        y: number;
+        y?: number;
        z: number;
+        radius?: number;
    };
    /** 关联的 3D 场景节点名（可选） */
    sourceNodeName?: string;
@@ -486,6 +558,26 @@ interface SgsSpaceArea {
    status: 'ACTIVE' | 'INACTIVE';
    /** 颜色（十六进制，如 #0097A9） */
    colorHex?: string;
+    /** 简介 */
+    description?: string | null;
+    /** 英文简介 */
+    descriptionEn?: string | null;
+    /** 封面图 */
+    coverImageUrl?: string | null;
+    /** 图集 */
+    images?: string | string[] | null;
+    /** 兼容展厅表图集字段 */
+    galleryUrls?: string | string[] | null;
+    /** 视频 */
+    videoUrl?: string | null;
+    /** 外部详情链接 */
+    externalUrl?: string | null;
+    /** 开放时间 */
+    openTime?: string | null;
+    /** 展品数量 */
+    exhibitCount?: number | null;
+    /** 面积 */
+    areaSqm?: number | null;
 }
 /** v2.2.0 讲解点 — 已标定、可在地图定位的导览讲解点 */
 interface SgsGuideStop {
@@ -577,6 +669,10 @@ interface SgsPerformanceStats {
    dracoUsed?: boolean;
    /** 是否使用了 fallback 模型 */
    fallbackUsed?: boolean;
+    /** Bundle 是否命中前端缓存 */
+    bundleCacheHit?: boolean;
+    /** 当前加载的模型 URL */
+    currentModelUrl?: string;
    /** 当前楼层 ID */
    currentFloorId?: string | number;
 }
@@ -590,6 +686,11 @@ interface SgsNavigablePlace {
    x: number;
    z: number;
    nodeId?: string | number;
+    routeNodeId?: string | number;
+    sourceType?: "POI" | "SPACE" | "FLOOR" | "CUSTOM" | string | null;
+    sourceId?: string | number | null;
+    anchorId?: string | number | null;
+    anchorType?: string | null;
    ownerName?: string;
    typeCode?: string;
    typeName?: string;
@@ -726,11 +827,90 @@ interface SgsFeaturedRouteDetail extends SgsFeaturedRouteSummary {
    endEntrance?: SgsRouteEndpoint | null;
    waypoints: SgsFeaturedRouteWaypoint[];
 }
+interface SgsFeaturedRoutePreviewPayload {
+    routeId?: string | number;
+    routeName?: string;
+    color?: string | null;
+    routeColor?: string | null;
+    startEntrance?: SgsRouteEndpoint | null;
+    endEntrance?: SgsRouteEndpoint | null;
+    waypoints?: SgsFeaturedRouteWaypoint[];
+}
+interface SgsRouteRoamingOptions {
+    mode?: 'third-person' | 'top';
+    speed?: number;
+}
+interface SgsGuideNavigationGraphResp {
+    floorId: string | number;
+    floorCode?: string | null;
+    status?: string | null;
+    graphJson?: string | null;
+    updatedAt?: string | null;
+}
 interface SgsFlowlineOptions {
    autoFit?: boolean;
    showLabels?: boolean;
    animate?: boolean;
 }
+/** POI 标签项（单个或聚合） */
+interface SgsPoiLabelItem {
+    id: string;
+    labelKind: 'SINGLE' | 'CLUSTER';
+    lod: 'FAR' | 'MID' | 'NEAR';
+    floorId: string | number;
+    floorCode?: string;
+    name: string;
+    type?: string;
+    typeName?: string;
+    category?: string;
+    categoryName?: string;
+    poiGroup?: string;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    labelPosition?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    positionSource?: string;
+    labelSource?: string;
+    priority?: number;
+    childCount?: number;
+    childPoiIds?: string[];
+    defaultVisible?: boolean;
+    sortOrder?: number;
+}
+/** POI 标签楼层数据 */
+interface SgsPoiLabelFloor {
+    floorId: string | number;
+    floorCode: string;
+    floorName?: string;
+    sortOrder?: number;
+    farLabels: SgsPoiLabelItem[];
+    midLabels: SgsPoiLabelItem[];
+    nearLabels: SgsPoiLabelItem[];
+}
+/** POI 标签摘要统计 */
+interface SgsPoiLabelSummary {
+    floorCount: number;
+    farLabelCount: number;
+    midLabelCount: number;
+    nearLabelCount: number;
+    sourcePoiCount: number;
+    clusterCount: number;
+    singleCount: number;
+}
+/** POI Label LOD Bundle 响应 */
+interface SgsPoiLabelLodBundle {
+    mapId: string | number;
+    dataVersion?: string;
+    floors: SgsPoiLabelFloor[];
+    summary: SgsPoiLabelSummary;
+    updatedAt?: string;
+}

 /**
 * 过滤 EXTERIOR 楼层，检查楼层是否是室内可导航楼层
@@ -756,7 +936,7 @@ declare namespace utils {
 * <p>所有需要后端数据的操作均通过 postMessage 指令由底座代理，
 *    Demo / 宿主不允许直连后端 API。
 *
- * @version 2.4.0
+ * @version 2.4.1
 */
 declare class SGSMapSDK extends EventEmitter<SGSMapEvents> {
    static utils: typeof utils;
@@ -858,7 +1038,9 @@ declare class SGSMapSDK extends EventEmitter<SGSMapEvents> {
    /** 聚焦到指定要素节点 */
    focusTo(node: SgsMapNode | string): void;
    /** 切换楼层 */
-    changeFloor(floorId: string | number, timeout?: number): Promise<{
+    changeFloor(floorId: string | number, timeout?: number, options?: {
+        forceReload?: boolean;
+    }): Promise<{
        success: boolean;
        floorId: string | number;
    }>;
@@ -876,7 +1058,52 @@ declare class SGSMapSDK extends EventEmitter<SGSMapEvents> {
    planRouteV2(from: SgsMapNode, to: SgsMapNode, options?: any, timeout?: number): Promise<RouteResult>;
    /** 清除当前路线 */
    clearRoute(): void;
-    /** 获取引擎状态 */
+    /** 渲染已有路线点，供外部宿主直接展示自定义路线 */
+    renderRoutePoints(pathPoints: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>, options?: any, timeout?: number): Promise<RouteResult>;
+    /** 启动路线漫游；pathPoints 为空时，基座会优先使用当前已渲染路线 */
+    startRoaming(pathPoints?: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>, options?: SgsRouteRoamingOptions, timeout?: number): Promise<{
+        success: boolean;
+        mode?: string;
+    }>;
+    /** 停止路线漫游 */
+    stopRoaming(timeout?: number): Promise<{
+        success: boolean;
+    }>;
+    /** 暂停或继续路线漫游 */
+    toggleRoamingPause(timeout?: number): Promise<{
+        success: boolean;
+        paused?: boolean;
+    }>;
+    /**
+     * 导航至POI（SDK 2.4.1）
+     *
+     * 支持从坐标或POI导航到目标POI，后端自动查询POI坐标。
+     *
+     * @param from 起点（POI ID字符串/数字 或 坐标对象）
+     * @param toPoiId 目标POI ID（建议使用string避免Snowflake精度丢失）
+     * @param options 路径选项（wheelchair, preferElevator）
+     * @param timeout 超时时间（毫秒）
+     */
+    planRouteToPoi(from: string | number | SdkRoutePoint, toPoiId: string | number, options?: RouteOptions, timeout?: number): Promise<RouteResult>;
+    /**
+     * POI间导航（SDK 2.4.1）
+     *
+     * 两个POI之间的导航，后端自动查询POI坐标。
+     *
+     * @param fromPoiId 起点POI ID
+     * @param toPoiId 终点POI ID
+     * @param options 路径选项（wheelchair, preferElevator）
+     * @param timeout 超时时间（毫秒）
+     */
+    planRouteBetweenPois(fromPoiId: string | number, toPoiId: string | number, options?: RouteOptions, timeout?: number): Promise<RouteResult>;
    getState(): Promise<any>;
    /** 重置视角 */
    resetView(timeout?: number): Promise<{
@@ -944,6 +1171,8 @@ declare class SGSMapSDK extends EventEmitter<SGSMapEvents> {
    }, timeout?: number): Promise<SgsFeaturedRouteSummary[]>;
    /** 获取特色路线详情 */
    getFeaturedRoute(routeId: string | number, timeout?: number): Promise<SgsFeaturedRouteDetail>;
+    /** 生成并展示精品路线预览 */
+    planFeaturedRoutePreview(payload: SgsFeaturedRoutePreviewPayload, timeout?: number): Promise<RouteResult>;
    /** 显示动线 */
    showFlowline(routeId: string | number, options?: SgsFlowlineOptions, timeout?: number): Promise<{
        success: boolean;
@@ -968,4 +1197,4 @@ declare class SGSMapSDK extends EventEmitter<SGSMapEvents> {
    destroy(): void;
 }

-export { type MarkerConfig, type RouteOptions, type RouteResult, type SGSErrorCode, type SGSMapEvents, type SGSMapSDKOptions, type SgsBusinessPoiType, type SgsFeaturedRouteDetail, type SgsFeaturedRouteSummary, type SgsFeaturedRouteWaypoint, type SgsFloorBundle, type SgsFloorDiagnostics, type SgsFloorDiagnosticsSummary, type SgsFloorResource, type SgsFlowlineOptions, type SgsGuideStop, type SgsLayerTreeNode, type SgsMapDiagnostics, type SgsMapManifest, type SgsMapNode, type SgsModelResource, type SgsNavigablePlace, type SgsPerformanceStats, type SgsPoi, type SgsPoiGroup, type SgsPoiQueryParams, type SgsRouteEndpoint, type SgsRoutePlanV2, type SgsRouteSegment, type SgsRouteSegmentType, type SgsRouteTransferType, type SgsSdkError, type SgsSdkFloorSummary, type SgsSdkManifest, type SgsSpaceArea, type SnapDetail, SGSMapSDK as default };
+export { type MarkerConfig, type RouteOptions, type RouteResult, type SGSErrorCode, type SGSMapEvents, type SGSMapSDKOptions, type SdkRoutePoint, type SgsBusinessPoiType, type SgsFeaturedRouteDetail, type SgsFeaturedRoutePreviewPayload, type SgsFeaturedRouteSummary, type SgsFeaturedRouteWaypoint, type SgsFloorBundle, type SgsFloorDiagnostics, type SgsFloorDiagnosticsSummary, type SgsFloorResource, type SgsFlowlineOptions, type SgsGuideNavigationGraphResp, type SgsGuideStop, type SgsLayerTreeNode, type SgsMapDiagnostics, type SgsMapManifest, type SgsMapNode, type SgsModelResource, type SgsNavigablePlace, type SgsPerformanceStats, type SgsPoi, type SgsPoiGroup, type SgsPoiLabelFloor, type SgsPoiLabelItem, type SgsPoiLabelLodBundle, type SgsPoiLabelSummary, type SgsPoiQueryParams, type SgsRouteAsset, type SgsRouteEndpoint, type SgsRoutePlanV2, type SgsRouteRoamingOptions, type SgsRouteSegment, type SgsRouteSegmentType, type SgsRouteTransferType, type SgsSdkError, type SgsSdkFloorSummary, type SgsSdkManifest, type SgsSpaceArea, type SnapDetail, SGSMapSDK as default };
--- a/static/sgs-map-sdk/index.global.js
+++ b/static/sgs-map-sdk/index.global.js
--- a/static/sgs-map-sdk/index.global.js.map
+++ b/static/sgs-map-sdk/index.global.js.map
--- a/static/sgs-map-sdk/index.mjs
+++ b/static/sgs-map-sdk/index.mjs
--- a/static/sgs-map-sdk/index.mjs.map
+++ b/static/sgs-map-sdk/index.mjs.map
--- a/static/sgs-map-sdk/package.json
+++ b/static/sgs-map-sdk/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@sgs/map-sdk",
-  "version": "2.4.0",
+  "version": "2.4.1",
  "description": "SGS Map SDK API contract copy for frontend-miniapp; iframe runtime is not enabled by this project",
  "main": "./index.global.js",
  "types": "./index.d.ts",
@@ -14,6 +14,9 @@
  "files": [
    "index.global.js",
    "index.global.js.map",
+    "index.mjs",
+    "index.mjs.map",
+    "index.d.mts",
    "index.d.ts",
    "README.md",
    "CHANGELOG.md",
--- a/static/sgs-map-sdk/sdk-quickstart.md
+++ b/static/sgs-map-sdk/sdk-quickstart.md
@@ -44,7 +44,14 @@ SDK 通过 `sdkUrl` 连接独立渲染基座。正式接入时请使用地图服
 https://map.museum.com/h5-sdk
 ```

-本 SDK 发布包不附带产品化 Demo。Demo 将作为独立交付物在后续版本中重构，不作为当前 SDK 接入前置条件。
+发布包内附带 `demo/` 目录，是一个完整的 SDK 能力展示页面。运行方式：
+
+```bash
+# 在 sgs-map-sdk-release 根目录下
+npx -y serve . -l 5555
+# 浏览器打开（?server= 指向运行中的地图服务）
+# http://localhost:5555/demo/?server=http://localhost:3001
+```

 ---

--- a/tests/unit/SgsMapService.spec.ts
+++ b/tests/unit/SgsMapService.spec.ts
@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type {
+  SgsMapEvents,
+  SgsMapSDKConstructor,
+  SgsMapSDKInstance
+} from '@/types/sgs-map-sdk'
+
+const loadSgsMapScript = vi.hoisted(() => vi.fn())
+
+vi.mock('@/services/sgs/SgsMapScriptLoader', () => ({
+  loadSgsMapScript
+}))
+
+import { SgsMapService } from '@/services/sgs/SgsMapService'
+
+const createHarness = async () => {
+  const listeners = new Map<keyof SgsMapEvents, (payload: never) => void>()
+  const sdk = {
+    on: vi.fn((event: keyof SgsMapEvents, listener: (payload: never) => void) => {
+      listeners.set(event, listener)
+    }),
+    off: vi.fn(),
+    getIsReady: vi.fn(() => true),
+    changeFloor: vi.fn().mockResolvedValue({ success: true, floorId: 'L2' }),
+    resetView: vi.fn().mockResolvedValue({ success: true }),
+    setViewMode: vi.fn().mockResolvedValue({ success: true, mode: '2d' }),
+    destroy: vi.fn()
+  } as unknown as SgsMapSDKInstance
+  const SDKConstructor = vi.fn(() => sdk) as unknown as SgsMapSDKConstructor
+
+  loadSgsMapScript.mockResolvedValue(SDKConstructor)
+
+  const service = new SgsMapService({
+    container: {} as HTMLElement,
+    scriptUrl: '/static/sgs-map-sdk/index.global.js?v=2.4.1',
+    sdkUrl: '/h5-sdk',
+    targetOrigin: 'https://map.example.com',
+    floorId: 'L1',
+    timeout: 7000
+  })
+  const ready = service.init()
+
+  await vi.waitFor(() => expect(SDKConstructor).toHaveBeenCalledOnce())
+  listeners.get('ready')?.({
+    engineVersion: '2.4.1',
+    protocolVersion: 2
+  } as never)
+  await ready
+
+  return { sdk, service }
+}
+
+beforeEach(() => {
+  loadSgsMapScript.mockReset()
+})
+
+describe('SGS Map SDK 2.4.1 service adapter', () => {
+  it('透传楼层强制刷新选项和统一命令超时', async () => {
+    const { sdk, service } = await createHarness()
+
+    await expect(service.changeFloor('L2', { forceReload: true })).resolves.toEqual({
+      success: true,
+      floorId: 'L2'
+    })
+    expect(sdk.changeFloor).toHaveBeenCalledWith('L2', 7000, { forceReload: true })
+  })
+
+  it('返回异步视图命令结果并向上传递 SDK 错误', async () => {
+    const { sdk, service } = await createHarness()
+
+    await expect(service.setViewMode('2d')).resolves.toEqual({ success: true, mode: '2d' })
+    expect(sdk.setViewMode).toHaveBeenCalledWith('2d', 7000)
+
+    vi.mocked(sdk.resetView).mockRejectedValueOnce(new Error('RESET_VIEW failed'))
+    await expect(service.resetView()).rejects.toThrow('RESET_VIEW failed')
+    expect(sdk.resetView).toHaveBeenCalledWith(7000)
+  })
+})