27-cesium-viewer-integration.md 3.5 KB
27: 接入 Cesium 常驻 Viewer（引擎接入）
What to build: 把中央一张图的宿主接到真实引擎上：装 cesium，按决策地图的 Cesium 调研配方配置静态资源与 CESIUM_BASE_URL，由地图服务层在现有宿主要素上创建唯一 Viewer，并让尺寸变化与销毁也走服务层。外壳与 MapCanvas 组件不改。
（本票来自票 02 验收清单未覆盖的部分：决策地图把「创建 Cesium Viewer」写给票 02，但票 02 的验收只要求常驻/生命周期，故独立成票。归属由维护者 2026-09-16 决定。）
Blocked by: 02
Status: ready-for-agent Labels: ready-for-agent Category: enhancement
依赖与事实
- 决策地图的 Cesium 调研：Cesium integration into Fes and Vite，产物 cesium-fes-vite.md（含冲突清单、静态资源拷贝、
CESIUM_BASE_URL时序、禁止项） —— 注意跨 effort 同号：这里的「06」指决策地图的调研票，不是本 effort 的issues/06（驾驶舱静态资产）。 - 环境已核实：npm registry 可达，
cesium@1.145.0可装 - ADR 0004：Cesium 为主、Three.js 为增强；ADR 0008：相机契约（三键）在票 03 实现
验收
- 安装
cesium为运行时依赖（版本固定），不放进 federation 的shared，并加入manualChunks单独分包。 - 构建期把
node_modules/cesium/Build/Cesium/{Workers,ThirdParty,Assets,Widgets}拷到产物cesium/目录，且在yarn dev与pre.dev.one（copyPublicDir:false）两种模式下都生效。 -
window.CESIUM_BASE_URL在 importcesium之前设置，取值来自publicPath: './'（qiankun 下用__INJECTED_PUBLIC_PATH_BY_QIANKUN__），不硬编码/cesium/。 -
services/mapService.js在宿主要素上创建唯一Viewer：mountMap()仍是幂等的、resizeMap()转调viewer.resize()、unmountMap()转调viewer.destroy()；getLifecycleStats()语义不变。 - 不使用 Ion token、
Terrain.fromWorldTerrain、createOsmBuildings等需要账号的能力（票 06 明令禁止）。 - 关闭 Cesium 自带的默认控件与默认相机输入（导航控件、时间轴等）——默认左键旋转/滚轮缩放会与票 03 的三键契约打架。
- 底图未配置时不伪造地理配准：显示明确的「底图未配置」状态，而不是把临时影像硬塞进某个假坐标范围。
- 引擎初始化失败时页面不白屏：给出明确失败状态，中央区域仍有可读兜底（现有临时影像或纯色 + 文案）。
- 现有的 17 项走查断言全部仍然通过（尤其是 A14 地图宿主实例 id 不变、A12 铺满几何）。
- 新增可观测证据：走查断言宿主内只有 1 个 Cesium 画布、实例 id 跨模式切换与面板收放保持不变、且 worker 静态资源可访问（HTTP 200）。
- 逻辑断言脚本中的地图服务生命周期一节继续通过（幂等挂载、只创建一次、销毁语义）。
不在本票范围
- 相机三键契约（票 03）、3D Tiles/地形/倾斜摄影（票 21）、管线渲染（票 22）、监测点与事件图层（票 08/09）。
- 真底图来源（天地图/甲方本地瓦片）：票 06 调研定性为「底图校验」与正式资源两条路，归票 21。
进度：0%
已立案。归属与依赖由维护者确认（新增票 27，并作为票 03 的前置——三键相机契约必须落在真实引擎上）。