sgs-map-sdk-release/
├── dist/                        # SDK 代码产物包（核心）
│   ├── index.global.js          # 给大屏端或传统网页使用的 IIFE 格式（通过 <script> 引入）
│   ├── index.global.js.map      # IIFE source map
│   ├── index.mjs                # 给 Webpack / Vite / Next.js 等现代工程使用的 ESM 格式
│   ├── index.mjs.map            # ESM source map
│   ├── index.d.ts               # TypeScript 类型声明文件
│   └── index.d.mts              # TypeScript 模块声明文件
├── demo/                        # SDK 能力展示 Demo（可直接运行）
│   ├── index.html               # Demo 入口页面
│   ├── app.js                   # Demo 应用逻辑
│   └── styles.css               # Demo 样式表
├── package.json                 # NPM 元信息
├── CHANGELOG.md                 # 版本变更日志
├── RELEASE_NOTES_2.4.0.md       # V2.4.0 正式发布说明
├── sdk-quickstart.md            # 【必读】10 分钟快速接入指南（含完整示例代码）
├── sdk-api-reference.md         # 【必读】第三方开发 API 参考手册
├── sdk-protocol.md              # 【选读】底层通信协议与安全沙箱规范说明
└── README.md                    # 当前说明文档

🚀 环境对接配置信息 (非常重要)

在下游业务端执行 new SGSMapSDK({ ... }) 初始化时，必须要填入由服务端分配的环境对接变量：

sdkUrl（渲染基座地址）：
- 释义：独立渲染基座的 URL 路径，SDK 会自动在您的页面中创建一个不可见的 iframe 或 Web-View 连接到这里。
- 请联系地图管理平台管理员获取最新的正式/测试域名，例如：https://map.museum.com/engine/index.html。
targetOrigin（安全通信域）：
- 释义：这是指地图渲染基座的来源域名（即 sdkUrl 的 Origin）。为了安全，SDK 只接收来自该域名 iframe 的消息。
- 配置要求：请传入独立 SDK Engine 的部署域名，例如：https://map.museum.com。如果不传，SDK 会自动从 sdkUrl 参数推导。注意：不要填成业务页面的域名。

📦 独立渲染基座部署与版本关系

部署要求：本 SDK 是“双域架构”。除了在您的业务前端引入 sgs-map-sdk 库以外，SGS 统一地图管理平台必须在您的服务器或内网环境中完成独立部署（基座项目为 sgs-frontend-map）。
版本对应：SDK 与基座严格遵守大版本一致原则。例如，SDK V2.x.x 必须对应基座引擎的 V2.x.x。如果强行跨版本混用，HELLO 协议握手将被拒绝并抛出 ERR_NOT_READY。

📤 发布目录说明

用途	目录/入口	说明
SDK 独立交付包	`E:\sgs-dm\sgs-map-sdk-release`	对外交付 SDK、类型声明、示例和接入文档
SDK 包产物	`E:\sgs-dm\sgs-map-sdk-release\dist`	保留 `index.global.js`、`index.mjs`、`index.d.ts` 等包内标准命名
前端公开 SDK	`E:\sgs-dm\sgs-frontend-map\public\sdk`	Next 静态目录，对外路径为 `/sdk/sgs-map-sdk.min.js`

从 sgs-frontend-map 执行 npm run build:sdk 后，会自动构建 dist/sdk，并同步到 public/sdk 与 sgs-map-sdk-release/dist。正式发布前以这三个目录的产物一致性作为验收口径。

📚 如何开始？

快速体验 Demo：发布包内附带 demo/ 目录，是一个完整的 SDK 能力展示页面，支持空间查询、POI 查询、讲解点、导航规划、诊断等全部功能。运行方式：
```
npx -y serve . -l 5555
# 浏览器打开（?server= 指向运行中的地图服务）
# http://localhost:5555/demo/?server=http://localhost:3001
```
如果您是普通前端业务开发 / 微信小程序开发：直接打开 sdk-quickstart.md，复制里面的示例代码，10分钟即可完成接入。 (注：微信小程序团队完全无需引入 dist 下的代码，请仔细阅读文档中小程序 <web-view> 的原生接入方式)
如果您需要逐个查询 API 参数、返回值和错误码：打开 sdk-api-reference.md，按方法名查阅第三方调用说明。
如果您需要了解 V2.4.0 新版本变化与发布边界：打开 RELEASE_NOTES_2.4.0.md，查看业务 POI、精品路线、动线展示、兼容性和已验证范围。
如果您是对架构感兴趣的高级开发：可以阅读 sdk-protocol.md，了解我们如何通过双域确权协议解决 postMessage 多实例安全问题，以及 WebGL 的安全释放机制。

🆕 V2.4.0 当前能力概览

V2.4.0 新增方法

方法	签名	说明
`getBusinessPois`	`getBusinessPois(floorId: string \| number, options?: any)`	获取指定楼层的业务 POI（例如商铺、餐饮等），与基础设施 POI 分离
`queryPois`	`queryPois(params: SgsPoiQueryParams)`	灵活的多字段 POI 检索接口，支持按地图、楼层、分组、类型、关键词组合查询
`getFeaturedRoutes`	`getFeaturedRoutes(mapId: string \| number, options?: any)`	获取当前地图关联的特色精选路线列表摘要
`getFeaturedRoute`	`getFeaturedRoute(routeId: string \| number)`	根据路线 ID 获取特色精选路线的详细路点序列与说明
`showFlowline`	`showFlowline(routeId: string \| number)`	在地图上高亮渲染展示一条特色动线（自动切换至全局俯瞰视角）
`clearFlowline`	`clearFlowline()`	清除当前展示的特色动线并恢复默认视图

V2.3.0 基础数据能力

V2.3.0 新增方法

方法	签名	说明
`getNavigablePlaces`	`getNavigablePlaces(floorId: string \| number)`	获取指定楼层可用于导航的目的地列表，优先返回业务门点并过滤纯交通设施本体
`getDiagnostics`	`getDiagnostics()`	获取地图级健康诊断，包含楼层、模型、POI、空间、讲解点、路网和可导航目的地统计
`getFloorDiagnostics`	`getFloorDiagnostics(floorId: string \| number)`	获取单楼层详细诊断，用于发布前检查数据完整性

V2.3.0 Manifest 能力字段

manifest.capabilities 新增标准能力声明：

mapLoading, floorSwitching, poiQuery, spaceQuery,
navigablePlaces, crossFloorRoute, accessibleRoute,
highlight, diagnostics

下游业务端应优先通过 capabilities 判断当前地图基座是否支持对应能力。

V2.2.0 基础数据能力

新增方法 (8 个)

方法	签名	说明
`getManifest`	`getManifest()`	获取地图 Manifest（地图元数据、楼层列表等）
`loadFloorBundle`	`loadFloorBundle(floorId: string \| number)`	加载楼层 Bundle（模型 + POI + 空间面 + 讲解点一次性拉取）
`getFloorPois`	`getFloorPois(floorId: string \| number)`	获取指定楼层的 POI 列表
`getSpaces`	`getSpaces(floorId: string \| number)`	获取指定楼层的空间面（展厅/分区）列表
`getGuideStops`	`getGuideStops(floorId: string \| number)`	获取指定楼层的讲解点列表
`preloadFloor`	`preloadFloor(floorId: string \| number)`	预加载指定楼层（后台静默下载模型资源，不切换视图）
`clearModelCache`	`clearModelCache()`	清空本地模型缓存（IndexedDB / Memory）
`getPerformanceStats`	`getPerformanceStats()`	获取性能统计（FPS、DrawCall、纹理内存等）

类型放宽：v2.2.0 继续保持所有 ID 字段（floorId、mapId、poiId 等）支持 string | number，兼容字符串形式的业务 ID。

新增事件 (5 个)

事件名	Payload	说明
`modelLoading`	`{ floorId, modelUrl }`	模型文件开始加载（可用于显示 Loading UI）
`modelReady`	`{ floorId, parseTimeMs }`	模型解析完成，Three.js Scene 已挂载
`modelError`	`{ floorId, error, fallbackUsed }`	模型加载失败，含是否使用了 fallback 回退信息
`floorBundleReady`	`{ floorId, dataVersion }`	楼层 Bundle 数据全部就绪
`routeReady`	`{ routeId, distance, duration }`	路径规划完成，返回距离/时长

Draco 压缩策略

v2.2.0 的模型管线保持自动 Draco 压缩策略：

导入阶段：GLB 模型导入后，服务端自动执行保守级 Draco 压缩（quantization position=14, normal=10, texcoord=12）
容错机制：若 Draco 压缩失败（如非标网格），系统自动回退使用原始 GLB 文件，不影响渲染
客户端解码：SDK 内置 Draco WASM 解码器，客户端无需任何额外配置
体积收益：典型博物馆楼层模型压缩率约 60%~75%，首屏加载时间显著缩短

README.md Unescape Escape

SGS Map SDK 交付包

📁 目录结构