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

SGS Map SDK 交付包

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

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

📁 目录结构

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 模块声明文件
├── example/
│   └── index.html               # 完整接入示例（带控制台、日志面板、与后端 API 联调）
├── package.json                 # NPM 元信息
├── sdk-quickstart.md            # 【必读】10 分钟快速接入指南（含完整示例代码）
├── 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-quickstart.md，复制里面的示例代码，10分钟即可完成接入。 (注：微信小程序团队完全无需引入 dist 下的代码，请仔细阅读文档中小程序 <web-view> 的原生接入方式)

• 如果您想看一份能直接跑的完整示例： 打开 example/index.html，用本地静态服务器（如 npx serve）打开即可，里面包含楼层切换、聚焦、寻路、图钉、超时、销毁等全场景演示。需要先把基座 sgs-frontend-map 跑起来并把 sdkUrl 改成对应的本地地址。

• 如果您是对架构感兴趣的高级开发： 可以阅读 sdk-protocol.md，了解我们如何通过双域确权协议解决 postMessage 多实例安全问题，以及 WebGL 的安全释放机制。