frontend-miniapp/static/sgs-map-sdk/README.md

# SGS Map SDK 交付包

> **版本**：V2.4.0
> **定位**：深圳自然博物馆统一三维高精地图导航服务平台 H5 SDK

欢迎接入 SGS Map SDK！本 SDK 将复杂的 WebGL 三维渲染、GLB 模型管线与 NavMesh 物理寻路引擎封装在服务端基座中，业务端（H5 / 大屏 / 小程序）只需通过几行代码即可极速唤起 3D 地图。

## 📁 目录结构

```text
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({ ... })` 初始化时，必须要填入由服务端分配的**环境对接变量**：

1. **`sdkUrl`（渲染基座地址）**：
   - 释义：独立渲染基座的 URL 路径，SDK 会自动在您的页面中创建一个不可见的 iframe 或 Web-View 连接到这里。
   - **请联系地图管理平台管理员获取最新的正式/测试域名**，例如：`https://map.museum.com/h5-sdk`。

2. **`targetOrigin`（安全通信域）**：
   - 释义：这是指**地图渲染基座的来源域名**（即 `sdkUrl` 的 Origin）。为了安全，SDK 只接收来自该域名 iframe 的消息。
   - 配置要求：请传入您的地图基座部署域名，例如：`https://map.museum.com`。如果不传，SDK 会自动从 `sdkUrl` 参数推导。注意：**不要**填成您业务页面的域名（业务页面的域名是交给 h5-sdk 做白名单校验的）。

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

- **部署要求**：本 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 查询、讲解点、导航规划、诊断等全部功能。运行方式：
  ```bash
  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` 新增标准能力声明：

```text
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%，首屏加载时间显著缩短