提交室内导览交互与讲解优化

static/sgs-map-sdk/README.md

@@ -0,0 +1,54 @@
+# SGS Map SDK 交付包
+
+> **版本**：V2.0.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 模块声明文件
+├── 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 的安全释放机制。