更新 SGS 地图 SDK 并补充数据层接入手册
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# SGS Map SDK 交付包
|
||||
|
||||
> **版本**：V2.0.0
|
||||
> **版本**：V2.3.0
|
||||
> **定位**：深圳自然博物馆统一三维高精地图导航服务平台 H5 SDK
|
||||
|
||||
欢迎接入 SGS Map SDK！本 SDK 将复杂的 WebGL 三维渲染、GLB 模型管线与 NavMesh 物理寻路引擎封装在服务端基座中，业务端（H5 / 大屏 / 小程序）只需通过几行代码即可极速唤起 3D 地图。
|
||||
@@ -16,10 +16,9 @@ sgs-map-sdk-release/
|
||||
│ ├── index.mjs.map # ESM source map
|
||||
│ ├── index.d.ts # TypeScript 类型声明文件
|
||||
│ └── index.d.mts # TypeScript 模块声明文件
|
||||
├── example/
|
||||
│ └── index.html # 完整接入示例（带控制台、日志面板、与后端 API 联调）
|
||||
├── package.json # NPM 元信息
|
||||
├── sdk-quickstart.md # 【必读】10 分钟快速接入指南（含完整示例代码）
|
||||
├── sdk-api-reference.md # 【必读】第三方开发 API 参考手册
|
||||
├── sdk-protocol.md # 【选读】底层通信协议与安全沙箱规范说明
|
||||
└── README.md # 当前说明文档
|
||||
```
|
||||
@@ -41,14 +40,84 @@ sgs-map-sdk-release/
|
||||
- **部署要求**：本 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`。正式发布前以这三个目录的产物一致性作为验收口径。
|
||||
|
||||
## 📚 如何开始？
|
||||
|
||||
- **如果您是普通前端业务开发 / 微信小程序开发**：
|
||||
直接打开 `sdk-quickstart.md`，复制里面的示例代码，10分钟即可完成接入。
|
||||
*(注：微信小程序团队完全无需引入 `dist` 下的代码，请仔细阅读文档中小程序 `<web-view>` 的原生接入方式)*
|
||||
|
||||
- **如果您想看一份能直接跑的完整示例**：
|
||||
打开 `example/index.html`，用本地静态服务器（如 `npx serve`）打开即可，里面包含楼层切换、聚焦、寻路、图钉、超时、销毁等全场景演示。需要先把基座 `sgs-frontend-map` 跑起来并把 `sdkUrl` 改成对应的本地地址。
|
||||
- **如果您需要逐个查询 API 参数、返回值和错误码**：
|
||||
打开 `sdk-api-reference.md`，按方法名查阅第三方调用说明。
|
||||
|
||||
- **如果您是对架构感兴趣的高级开发**：
|
||||
可以阅读 `sdk-protocol.md`，了解我们如何通过双域确权协议解决 `postMessage` 多实例安全问题，以及 WebGL 的安全释放机制。
|
||||
|
||||
---
|
||||
|
||||
## 🆕 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%，首屏加载时间显著缩短
|
||||
|
||||
Reference in New Issue
Block a user