# SGS Map SDK API Reference

> 本项目同步版本: V2.5.0
> 适用对象: 第三方 H5、大屏、Kiosk、业务前端开发人员

> 发布源保留了 V2.3.0 文档标题和历史 API 注释；实际发行版本以 `package.json` 与 `dist` 产物自报的 2.5.0 为准。本文不表示本项目已经接入或验证 SDK iframe renderer。

本文档按公开 SDK 方法组织，说明初始化参数、事件、常用 API、返回值和错误处理。快速接入请先阅读 `sdk-quickstart.md`，底层通信协议请阅读 `sdk-protocol.md`。

## 1. 接入入口

### Script 标签

```html
<script src="./dist/index.global.js"></script>
<script>
  const map = new SGSMapSDK({
    container: 'map-container',
    sdkUrl: 'https://map.example.com/engine/index.html',
    targetOrigin: 'https://map.example.com',
    floorId: 1
  });
</script>
```

如果 SDK 已随 `sgs-frontend-map` 发布到静态目录：

```html
<script src="/sdk/sgs-map-sdk.min.js?v=2.5.0"></script>
```

### ESM

```ts
import SGSMapSDK from './dist/index.mjs';

const map = new SGSMapSDK({
  container: document.getElementById('map-container')!,
  sdkUrl: 'https://map.example.com/engine/index.html',
  targetOrigin: 'https://map.example.com',
  floorId: 1
});
```

## 2. 初始化配置

```ts
interface SGSMapSDKOptions {
  container: string | HTMLElement;
  sdkUrl?: string;
  targetOrigin?: string;
  floorId?: string | number;
  mapId?: string | number;
  timeout?: number;
  readyTimeout?: number;
}
```

| 字段 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `container` | 是 | 无 | 地图 iframe 挂载容器，可传 DOM id 或 HTMLElement |
| `sdkUrl` | 否 | `/engine/index.html` | 独立发布的 SDK 渲染引擎地址 |
| `targetOrigin` | 否 | 从 `sdkUrl` 推导 | `postMessage` 安全通信域，生产环境建议显式填写 |
| `floorId` | 否 | `1` | 初始楼层 ID，支持字符串或数字 |
| `mapId` | 否 | `1` | 地图 ID，当前由 SDK 实例保存 |
| `timeout` | 否 | `5000` | 普通命令超时时间，单位 ms |
| `readyTimeout` | 否 | `30000` | 等待 `ENGINE_READY` 的最大时间，单位 ms |

生产环境必须保证 `sdkUrl` 可访问，并且 `targetOrigin` 与 `sdkUrl` 的 Origin 一致。

## 3. 生命周期

### `whenReady(): Promise<any>`

等待地图引擎 ready。所有需要基座响应的 API 建议在 ready 后调用。

```ts
await map.whenReady();
await map.changeFloor(2);
```

### `ready(): Promise<any>`

`whenReady()` 的别名。

### `getIsReady(): boolean`

返回 SDK 是否已收到基座 `ENGINE_READY`。

### `destroy(): void`

销毁 SDK 实例，清理 iframe、事件监听和所有挂起 Promise。销毁后再调用异步命令会返回 `ERR_DESTROYED`。

```ts
window.addEventListener('beforeunload', () => {
  map.destroy();
});
```

## 4. 状态查询

### `getCurrentFloor(): string | number`

返回 SDK 当前记录的楼层 ID。

### `getMapId(): string | number`

返回初始化时设置的 `mapId`。

### `getVersion(): string`

返回 SDK 版本号；本项目同步的 2.5.0 Bridge 返回 `"2.5.0"`。

### `getState(): Promise<any>`

向渲染基座查询内部状态。主要用于调试或 Demo 面板。

```ts
const state = await map.getState();
console.log(state);
```

## 5. 地图控制

### `changeFloor(floorId, timeout?): Promise<{ success: boolean; floorId: string | number }>`

切换楼层。成功后 SDK 内部当前楼层会同步更新。

```ts
await map.changeFloor(2);
```

### `focusTo(node): void`

镜头聚焦到 POI、GLB 节点或坐标。

```ts
map.focusTo({ type: 'poiId', value: 10001 });
map.focusTo({ type: 'nodeName', value: 'Hall_Dinosaur' });
map.focusTo({ type: 'coord', floorId: 1, x: 12.5, z: -8.2 });
map.focusTo('Hall_Dinosaur');
```

`SgsMapNode` 类型：

```ts
type SgsMapNode =
  | { type: 'coord'; floorId: string | number; x: number; z: number; y?: number }
  | { type: 'poiId'; value: string | number }
  | { type: 'nodeName'; value: string };
```

坐标统一使用 GLB/Three.js 米制坐标，水平面为 `x/z`，高度为 `y`。

### `resetView(): void`

重置相机视角。

### `setViewMode(mode): void`

切换 2D/3D 模式。

```ts
map.setViewMode('2d');
map.setViewMode('3d');
```

### `highlightPolygon(nodeName): void`

高亮指定 3D 场景节点对应的空间轮廓。

```ts
map.highlightPolygon('Hall_Area_01');
```

## 6. 图层控制

### `toggleLayer(types, visible, timeout?): Promise<{ success: boolean; visibleTypes: string[] }>`

批量控制指定类型图层的显示隐藏。

```ts
await map.toggleLayer(['TOILET', 'ELEVATOR'], true);
await map.toggleLayer(['STAIRS'], false);
```

### `setVisibleLayers(types, timeout?): Promise<{ success: boolean; visibleTypes: string[] }>`

设置当前可见的图层类型列表。

```ts
await map.setVisibleLayers(['TOILET', 'ELEVATOR', 'SERVICE_DESK']);
```

## 7. 图钉 Marker

### `addMarker(config): void`

添加业务图钉。

```ts
map.addMarker({
  id: 'user-location',
  name: '我的位置',
  iconUrl: 'https://example.com/avatar.png',
  position: { x: 10, y: 1.6, z: -5 }
});
```

`MarkerConfig`：

```ts
interface MarkerConfig {
  id: string;
  name?: string;
  iconUrl?: string;
  anchorNodeName?: string;
  position?: [number, number, number] | { x: number; y: number; z: number };
}
```

### `removeMarker(markerId): void`

移除指定图钉。

```ts
map.removeMarker('user-location');
```

### `clearMarkers(): void`

清空所有业务图钉。

## 8. 路径规划

### `planRoute(from, to, options?, timeout?): Promise<RouteResult>`

规划路线，兼容字符串节点名和结构化节点。

```ts
const route = await map.planRoute(
  { type: 'poiId', value: 8001 },
  { type: 'poiId', value: 9005 },
  { mode: 'walk' }
);

if (route.success) {
  console.log(route.distance, route.duration, route.pathPoints);
}
```

也可传节点名：

```ts
await map.planRoute('一楼南卫生间', '生态大展区');
```

### `planRouteV2(from, to, options?, timeout?): Promise<RouteResult>`

结构化参数版本。当前底层同样发送 `PLAN_ROUTE` 指令。

```ts
await map.planRouteV2(
  { type: 'coord', floorId: 1, x: 0, z: 0 },
  { type: 'coord', floorId: 1, x: 12, z: -6 },
  { mode: 'accessible' }
);
```

### `clearRoute(): void`

清除当前路线。

```ts
map.clearRoute();
```

`RouteResult` 主要字段：

```ts
interface RouteResult {
  success: boolean;
  distance: number;
  duration: number;
  pathPoints: Array<{ x: number; y: number; z: number }>;
  computeTimeMs: number;
  warnings: string[];
  errorCode?: string;
  message?: string;
}
```

## 9. 地图数据 API

### `getManifest(timeout?): Promise<SgsSdkManifest>`

获取地图 Manifest，包含地图名称、楼层摘要、能力声明和版本信息。

```ts
const manifest = await map.getManifest();
console.log(manifest.mapName, manifest.sdkVersion, manifest.floors);
```

### `loadFloorBundle(floorId, timeout?): Promise<SgsFloorBundle>`

一次性加载指定楼层的模型、POI、空间面、讲解点和路网摘要。

```ts
const bundle = await map.loadFloorBundle(1);
console.log(bundle.model.modelUrl);
console.log(bundle.pois.length, bundle.spaces.length, bundle.guideStops.length);
```

### `getFloorPois(floorId, timeout?): Promise<SgsPoi[]>`

获取指定楼层 POI 列表。

```ts
const pois = await map.getFloorPois(1);
pois.forEach(poi => console.log(poi.name, poi.type, poi.position));
```

### `getPois(floorCode, timeout?): Promise<SgsPoi[]>`

按楼层代码获取 POI 列表。该方法用于兼容既有基座能力，推荐新接入优先使用 `getFloorPois(floorId)`。

```ts
const pois = await map.getPois('L1');
```

### `getSpaces(floorId, timeout?): Promise<SgsSpaceArea[]>`

获取指定楼层空间面列表。

```ts
const spaces = await map.getSpaces(1);
spaces.forEach(space => console.log(space.name, space.boundaryWkt));
```

### `getGuideStops(floorId, timeout?): Promise<SgsGuideStop[]>`

获取指定楼层已标定讲解点列表。

```ts
const stops = await map.getGuideStops(1);
stops.forEach(stop => console.log(stop.name, stop.audioUrl));
```

### `getGuideStopsByHall(hallId, timeout?): Promise<SgsGuideStop[]>`

获取指定展厅下的讲解点列表。

```ts
const stops = await map.getGuideStopsByHall('hall-001');
```

### `preloadFloor(floorId, timeout?): Promise<{ cached: boolean }>`

后台预加载指定楼层模型资源，不切换当前视图。

```ts
await map.preloadFloor(2);
```

### `clearModelCache(): void`

清空客户端模型缓存。

```ts
map.clearModelCache();
```

### `getNavigablePlaces(floorId, timeout?): Promise<SgsNavigablePlace[]>`

获取指定楼层的可导航目的地列表（v2.3.0+）。

```ts
const places = await map.getNavigablePlaces(1);
places.forEach(place => console.log(place.name, place.category));
```

## 10. 诊断接口 (v2.3.0+)

### `getDiagnostics(timeout?): Promise<SgsMapDiagnostics>`

获取地图整体诊断信息，包含所有楼层摘要和汇总统计。用于检查数据完整性和就绪状态。

```ts
const diagnostics = await map.getDiagnostics();
console.log('地图状态:', diagnostics.status);
console.log('楼层总数:', diagnostics.summary.floorCount);
console.log('POI总数:', diagnostics.summary.poiCount);
console.log('可导航目的地总数:', diagnostics.summary.navigablePlaceCount);

// 检查警告信息
if (diagnostics.warnings.length > 0) {
  console.warn('诊断警告:', diagnostics.warnings);
}

// 遍历楼层摘要
diagnostics.floors.forEach(floor => {
  console.log(`${floor.floorName}: ${floor.status}, 可导航点=${floor.navigablePlaceCount}`);
});
```

**返回结构**:

```ts
interface SgsMapDiagnostics {
  mapId: string | number;
  mapName: string;
  sdkVersion: string;
  status: 'OK' | 'WARN' | 'ERROR';
  floors: SgsFloorDiagnosticsSummary[];
  summary: {
    floorCount: number;
    modelReadyFloorCount: number;
    poiCount: number;
    spaceCount: number;
    guideStopCount: number;
    navigablePlaceCount: number;
    routeNodeCount: number;
    routeEdgeCount: number;
  };
  warnings: string[];
}
```

### `getFloorDiagnostics(floorId, timeout?): Promise<SgsFloorDiagnostics>`

获取单个楼层的详细诊断信息。

```ts
const floorDiag = await map.getFloorDiagnostics(1);
console.log('楼层状态:', floorDiag.status);
console.log('模型就绪:', floorDiag.modelReady);
console.log('路径规划就绪:', floorDiag.routePlanningReady);
console.log('POI数量:', floorDiag.poiCount);
console.log('可导航目的地:', floorDiag.navigablePlaceCount);
```

**返回结构**:

```ts
interface SgsFloorDiagnostics {
  floorId: string | number;
  floorCode: string;
  floorName: string;
  status: 'OK' | 'WARN' | 'ERROR';
  modelReady: boolean;
  poiCount: number;
  spaceCount: number;
  guideStopCount: number;
  navigablePlaceCount: number;
  routeNodeCount: number;
  routeEdgeCount: number;
  routePlanningReady: boolean;
  warnings: string[];
}
```

**使用场景**:
- 应用启动时检查地图数据是否完整
- 排查路径规划失败原因（检查 routePlanningReady）
- 监控数据发布后的就绪状态
- 生成数据健康报告

## 11. 性能监控

### `getPerformanceStats(timeout?): Promise<SgsPerformanceStats>`

获取 SDK 与渲染基座的性能统计。v2.3.0 保持合并 SDK 自身耗时与基座返回的模型加载耗时。

```ts
const stats = await map.getPerformanceStats();
console.table({
  sdkReady: stats.engineReadyMs,
  iframeDom: stats.iframeDomReadyMs,
  manifest: stats.manifestLoadMs,
  bundle: stats.bundleLoadMs ?? 'N/A',
  model: stats.modelDownloadAndParseMs,
  firstRender: stats.firstRenderMs
});
```

主要字段：

| 字段 | 说明 |
|------|------|
| `sdkCreatedAt` | SDK 实例创建时间戳 |
| `iframeDomReadyMs` | iframe DOM 加载完成耗时 |
| `engineReadyMs` | 地图引擎 ready 耗时 |
| `manifestLoadMs` | Manifest 加载耗时 |
| `bundleLoadMs` | Bundle 加载耗时，未触发时可能为空 |
| `modelDownloadMs` | 模型下载耗时 |
| `modelDownloadAndParseMs` | 模型下载与解析总耗时 |
| `modelParseMs` | 模型解析耗时 |
| `firstRenderMs` | 首帧渲染耗时 |
| `routePlanMs` | 路径规划耗时 |
| `dracoUsed` | 是否使用 Draco 压缩模型 |
| `fallbackUsed` | 是否使用 fallback 原始模型 |
| `currentFloorId` | 当前楼层 ID |

## 11. 事件

SDK 继承事件能力，可通过 `on(eventName, handler)` 监听事件。

```ts
map.on('ready', (info) => {
  console.log('ready', info.engineVersion, info.protocolVersion);
});

map.on('poiClick', (poi) => {
  console.log('poi clicked', poi.id, poi.name);
});
```

| 事件名 | Payload | 说明 |
|--------|---------|------|
| `ready` | `{ engineVersion, protocolVersion }` | 基座完全挂载，可安全调用 API |
| `poiClick` | `{ id, name, type, floorId?, description? }` | 用户点击 POI |
| `floorChanged` | `{ floorId }` | 楼层切换完成 |
| `error` | `{ code, message }` | 基座或 SDK 异常 |
| `loadError` | `{ type, detail }` | 资源加载异常 |
| `routeTransfer` | `{ currentFloorId, targetFloorId, transferType, ... }` | 跨楼层换乘提示 |
| `modelLoading` | `{ floorId, modelUrl }` | 模型开始加载 |
| `modelReady` | `{ floorId, parseTimeMs }` | 模型解析完成 |
| `modelError` | `{ floorId, error, fallbackUsed }` | 模型加载失败 |
| `floorBundleReady` | `{ floorId, dataVersion }` | 楼层 Bundle 数据加载完成 |
| `routeReady` | `{ routeId, distance, duration }` | 路径规划完成 |

## 12. 常用类型摘要

### `SgsSdkManifest`

```ts
interface SgsSdkManifest {
  mapId: string | number;
  mapName: string;
  sdkVersion: string;
  protocolVersion: number;
  dataVersion: string;
  updatedAt: string;
  coordinateSystem: string;
  floors: SgsSdkFloorSummary[];
  capabilities: {
    dracoCompression: boolean;
    routePlanning: boolean;
    spatialQuery: boolean;
    guideStops: boolean;
    // v2.3.0 新增标准能力字段
    mapLoading?: boolean;
    floorSwitching?: boolean;
    poiQuery?: boolean;
    spaceQuery?: boolean;
    navigablePlaces?: boolean;
    crossFloorRoute?: boolean;
    accessibleRoute?: boolean;
    highlight?: boolean;
    diagnostics?: boolean;
  };
}
```

### `SgsPoi`

```ts
interface SgsPoi {
  id: string | number;
  name: string;
  type: string;
  typeName: string;
  floorCode: string;
  position: { x: number; y: number; z: number };
  status: 'ACTIVE' | 'INACTIVE';
  anchorNodeName?: string | null;
  description?: string;
  iconUrl?: string;
}
```

### `SgsSpaceArea`

```ts
interface SgsSpaceArea {
  id: string | number;
  name: string;
  type: string;
  floorId: string | number;
  boundaryWkt: string;
  center: { x: number; y: number; z: number };
  sourceNodeName?: string;
  status: 'ACTIVE' | 'INACTIVE';
  colorHex?: string;
}
```

### `SgsGuideStop`

```ts
interface SgsGuideStop {
  id: string | number;
  name: string;
  type: string;
  floorId: string | number;
  position: { x: number; y: number; z: number };
  targetType: string;
  targetId?: string | number;
  audioUrl?: string;
  coverImageUrl?: string;
  description?: string;
  status: 'ACTIVE' | 'INACTIVE';
  hallId?: string | number;
  hallName?: string;
}
```

完整类型以 `dist/index.d.ts` 为准。

## 13. 错误处理

所有 Promise API 失败时会 reject 一个 `{ code, message }` 结构。

```ts
try {
  await map.changeFloor(999);
} catch (err) {
  console.warn(err.code, err.message);
}
```

| 错误码 | 说明 |
|--------|------|
| `ERR_TIMEOUT` | 命令响应超时 |
| `ERR_READY_TIMEOUT` | ready 超时，基座未发出 `ENGINE_READY` |
| `ERR_NOT_READY` | SDK ready 失败后继续调用命令 |
| `ERR_DESTROYED` | SDK 实例已销毁 |
| `ERR_IFRAME_LOAD` | iframe 加载失败 |
| `ERR_UNAUTHORIZED` | Origin 校验失败 |
| `ERR_UNSUPPORTED` | 当前基座不支持该命令 |
| `ERR_NO_PATH` | 路径规划无可达路线 |
| `ERR_FLOOR_NOT_FOUND` | 楼层不存在或未发布 |
| `ERR_NETWORK` | 网络或接口异常 |

## 14. 废弃方法

以下方法保留签名用于兼容旧接入方，新项目不要使用：

| 方法 | 状态 | 替代方案 |
|------|------|----------|
| `getReleaseManifest()` | 已废弃，返回 `ERR_UNSUPPORTED` | `getManifest()` |
| `getModelResources()` | 已废弃，返回 `ERR_UNSUPPORTED` | `loadFloorBundle()` |
| `getLayerTree()` | 已废弃，返回 `ERR_UNSUPPORTED` | 暂无 |
| `loadMockReleaseRoute()` | 已废弃，返回 `ERR_UNSUPPORTED` | `planRoute()` |

## 15. 第三方接入检查清单

- 页面中存在 SDK 挂载容器，且容器有稳定宽高。
- `sdkUrl` 可在浏览器直接访问，并能加载独立发布的 `/engine/index.html`。
- `targetOrigin` 与 `sdkUrl` 的 Origin 一致。
- 所有地图控制 API 在 `await map.whenReady()` 后调用。
- 坐标统一使用 GLB/Three.js 米制坐标，水平面为 `x/z`。
- 页面卸载时调用 `map.destroy()`。
- 生产发布时 SDK、Engine 与后端 Manifest 的 `sdkVersion` 必须保持兼容；本次 Bridge 为 `2.5.0`，上线前需验证 `/engine/index.html` 真实加载 SDK Engine 并完成 `HELLO` -> `ENGINE_READY`。