# 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](../web-cockpit-decision-map/issues/06-cesium-fes-vite-integration.md)，产物 [cesium-fes-vite.md](../web-cockpit-decision-map/research/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` 在 **import `cesium` 之前**设置，取值来自 `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 的前置——三键相机契约必须落在真实引擎上）。