版本与兼容性

0.1.0 · 待发布候选

此页描述预期交付范围，不表示已向任何 registry 发布，也不表示已完成生产部署。 真实发布日期、tarball 校验和及验收结果由发布负责人在流程完成后填写。

组件	版本/约定
npm 包	@shardx-map/sdk@0.1.0
Cesium peer	>=1.146.0 <1.147.0，示例锁定 1.146.0
消费模式	ESM，原生 TypeScript / Vite，Cesium 由宿主提供
文档	VitePress 1.6.4，中文
registry 模板	Verdaccio 6 + Nginx HTTPS；生产另锁定镜像 digest
构建 Node.js	与仓库一致，>=22.12.0

交付范围包含地图创建/销毁、点/线/单外环面/DOM 要素、图层显隐与删除、视角设置/飞行/图层定位、 天地图矢量与影像及注记、Natural Earth/XYZ/WMTS 切换、图片 Marker、点聚合、3D Tiles、昼夜预设、click/error 事件、文本或 DOM 弹窗，以及 Cesium 资源复制 CLI。 围栏支持 Polygon/MultiPolygon、洞、岛屿和围栏外遮罩；支持实时更新遮罩、填充和边线。点支持描边，线支持实线/虚线/箭头/描边，普通面支持独立填充透明度，模型支持透明度、精度与包围盒更新。

官网交付 TGZ、独立 Demo ZIP、SHA-256 与八类可运行教程，主部署流程为宝塔 Nginx 静态站点。下载内容在下载页列出，尚未完成真实域名上线验收。

重要行为：createMap 与 addTilesetLayer 需要 await；flyTo 不等待动画完成，模型 flyToLayer 返回 Cesium 飞行完成结果； updateFeature 不允许修改 id/type；删除不存在对象会报错；同页实例共享资源根配置。 详细参数与返回值以API为准。

已知边界

不提供坐标系转换、GeoJSON 通用解析、普通 polygon 的多面/洞、地形服务配置、独立 glTF 模型接口、编辑器、 底图通用鉴权请求头或服务端地图渲染。3D Tiles 支持请求头；DOM 覆盖层不保证建筑物深度遮挡。地图操作工具类留待后续。 没有地图全量加载完成事件，底图网络失败可能在创建/切换成功后上报。 不要把原型中的图层操作能力推广为尚未实现的 GIS 能力。

真实供应商授权、天地图 key/域名、目标浏览器、远端 npm 发布、HTTPS 和备份恢复保留为外部验收项。 模板不包含真实 token、证书、地图服务密钥或已部署服务器。

升级与回退

升级 SDK 时阅读变更、锁定确切版本并重新运行消费项目验证；0.x 的破坏性行为也应明确记录，不能默认所有次版本无缝兼容。 升级 Cesium 必须先确认 peer 范围和 SDK 兼容性，并重新复制静态资源与 CSS。 升级 registry 镜像先备份数据与配置，并在隔离卷验证恢复及兼容性。

发布与回退参考发布流程，数据恢复参考备份与恢复。 dist-tag 回退不会修改已经锁定的依赖，宿主应用仍需重新安装、构建与部署。