驾驶舱自有静态资产

生产部署请先看 docs/cockpit-deployment.md —— 那里是给运维的操作手册（改哪个文件、怎么改、怎么自检）。本文件偏「开发期怎么接数据」。

本目录是驾驶舱唯一的静态资源位置：public/plugins/** 属于 TvT 插件体系，驾驶舱不得依赖它（票 06 验收第 1 条）。

现有内容

文件	性质	说明
`aerial.webp`	临时占位	维护者提供的沅陵影像，仅用于在真底图接入前看整体效果。无地理配准，不得据此推断坐标。真底图/瓦片归票 21，接入后本文件可删。

引用方式

组件里通过 Vite 的 import.meta.env.BASE_URL 拼路径取用，例如：

const base = import.meta.env.BASE_URL || '/'
const photoUrl = `${base}cockpit/aerial.webp`

这样在 publicPath: './' 与 qiankun 注入路径下都能取到，不要硬编码 /cockpit/...。

后续替换约定

设计公司交付正式视觉资源后：配色/字号/间距改 src/modules/cockpit/styles/tokens.css；图片类资源（图例图标、底图、纹理）放本目录，替换时保持文件名或改用新名 + 更新引用点。
替换资源不应引起 mode / panelId / 面板结构变化——票 06 验收第 4 条。结构由 src/modules/cockpit/domain/panelCatalog.js 决定，与视觉资源解耦。

部署配置（票 04）

后端地址、天地图、Cesium 与 WebSocket 一律从配置服务（src/modules/cockpit/services/cockpitConfig.js）读，前端不硬编码环境地址，也不保存账号或密钥。

放哪儿：把 config.example.json 复制成同目录的 config.json（已进 .gitignore）。构建时它随 public/ 一起进产物（dist/cockpit/config.json）。部署后改环境不需要重新构建：直接改产物里那个文件，或在网关/反向代理把这个路径指向你自己维护的配置。

覆盖顺序（后者覆盖前者，深合并）：

层	来源	用途
1	内置默认	`dataSource: mock`，一份配置都没有也能起
2	构建期 `VITE_COCKPIT_*`	本机联调，写 `.env.local`（已 gitignore）
3	`cockpit/config.json`	部署配置：同一个构建跑多环境
4	`globalThis.__COCKPIT_CONFIG__`	qiankun 主应用 / 网关注入（给了就不再拉文件）

构建期可用键：VITE_COCKPIT_DATA_SOURCE、VITE_COCKPIT_API_BASE_URL、VITE_COCKPIT_API_TOKEN、 VITE_COCKPIT_WS_URL、VITE_COCKPIT_WS_TOKEN、VITE_COCKPIT_TIANDITU_TOKEN、 VITE_COCKPIT_CESIUM_BASE_URL、VITE_COCKPIT_CONFIG_URL。

三态：ready（载入成功）/ missing（没有运行时配置，用内置默认）/ failed（拿到了但不可用）。顶栏有对应标签，宿主带 data-config-state 供走查断言。

凭据：api.token / ws.token 只用于开发与联调的只读令牌；生产由网关在转发 /api/cockpit/v1/** 时补 Authorization: Bearer <JWT>，配置里留空即可。凭据缺失或 401 时只把受影响分区标成「数据不可用」，不跳登录页、不整页遮罩（ADR 0005）。

一个坑：yarn dev 下 Vite 会把不存在的路径回退成 index.html + 200，所以配置服务把「HTML 载荷」也判定为「文件不存在」（missing）——不能只看状态码，见 services/cockpitConfig.js 顶部说明。

怎么配出一个基础地图场景（票 29）

中央一张图默认不挂底图（票 27：底图未配置就不伪造地理配准），所以你看到的是一个深色球。 map.basemap.source 四选一：

source	需要什么	适合
`none`（默认）	无	还没有底图，用临时影像兜底
`natural-earth`	无 —— Cesium 自带离线影像（随 `dist/cesium/Assets` 一起部署，不连外网）	想马上看到一个有大陆轮廓的地球
`tianditu`	`map.tianditu.token`（天地图 tk）；开发走仓库自带的 `/tianditu.map` 代理，生产直连 `t{s}.tianditu.gov.cn`	有天地图 key，要看国内影像/矢量
`xyz`	`map.basemap.url` 形如 `https://host/tiles/{z}/{x}/{y}.png`（可带 `{s}` 子域）	甲方本地瓦片、自建瓦片服务、第三方 XYZ

三种写法的例子：

// 1) 离线内置影像：改完刷新页面就是一个地球
"map": { "basemap": { "source": "natural-earth" } }

// 2) 天地图影像（token 由部署配置给；生产由网关注入也走同一个字段）
"map": { "basemap": { "source": "tianditu" }, "tianditu": { "token": "<你的 tk>", "layer": "img" } }

// 3) 本地/自建瓦片：url 可填相对路径（相对 index.html 解析），subdomains/levels 可选
"map": { "basemap": { "source": "xyz", "url": "tiles/{z}/{x}/{y}.png", "subdomains": [], "minimumLevel": 1, "maximumLevel": 18, "credit": "甲方基础地理" } }

怎么确认生效：宿主 .map-canvas 上的 data-map-basemap 会变成 natural-earth / xyz / tianditu（未配置是 not-configured，配置缺字段是 invalid），引擎浮标同时显示「底图：…」；配置无效时浮标会写明缺什么（例如「底图配置无效（天地图底图缺少 tk）· 回退临时影像」），不会白屏。

还没做的：地形、3D Tiles、倾斜摄影与地面-管线视图切换归票 21。

本地 / 甲方 GIS 数据怎么接（票 21）

两类数据、两个字段，形态决定写法：

数据	本机形态	配置字段	关键点
地形 DEM	`D:\GIS\GIS\yuanlingDEM`：cesiumlab 量化网格（`layer.json` + `{z}/{x}/{y}.terrain`，EPSG:4326、`scheme: "tms"`、带顶点法线）	`map.terrain.url`	`CesiumTerrainProvider.fromUrl(<目录>)` 直接吃 `layer.json`；`scheme: "tms"` 由 Cesium 自己认，服务端不要翻 y
影像切片	`D:\GIS\GIS\yuanlingPic3`：cesiumlab 切片（`meta.json` / `tilemapresource.xml`：EPSG:3857 + TMS，0–19 级 256px PNG）	`map.overlays[]`	TMS 的 y 自下而上 → 模板必须写 `{reverseY}`；把 `meta.json` 的 bounds 填进 `bounds`，范围外就不发请求（否则整球视角会刷 404）

本机开发

.env.local（已 gitignore）里两条：

COCKPIT_GIS_MOUNTS=[{"prefix":"/gis/dem","dir":"D:/GIS/GIS/yuanlingDEM"},{"prefix":"/gis/pic3","dir":"D:/GIS/GIS/yuanlingPic3"}]
VITE_COCKPIT_CONFIG_URL=auto

COCKPIT_GIS_MOUNTS 由 src/common/localGisStaticPlugin.js 在 dev server 上挂成静态路径 —— DEM 与影像上百 MB， 既不进仓库也不进产物；第二条打开本目录的 config.json（同样 gitignore）。

生产部署（改配置即可，不用重新构建）

两个目录放到服务器上（例如 /data/gis/...），nginx 挂出同样的 URL 前缀：

location /gis/dem/  { alias /data/gis/yuanlingDEM/;  add_header Cache-Control "public, max-age=86400"; }
location /gis/pic3/ { alias /data/gis/yuanlingPic3/; add_header Cache-Control "public, max-age=86400"; }

改产物里的 dist/cockpit/config.json：map.terrain.url → /gis/dem，map.overlays[0].url → /gis/pic3/{z}/{x}/{reverseY}.png （或指向另一台瓦片服务；前端只认这三个字段，换数据源就是换这几个 URL）。
.terrain 与 .png 都要能直接下载，别做 SPA 回退 —— 回退成 HTML 时 Cesium 会报「Unexpected token '<'」。

全局粗糙层

map.basemap.source 用 natural-earth：Cesium 自带离线影像，不依赖外网（本机实测 ArcGIS / OSM 等外部瓦片不可达，所以这是离线环境的唯一可用项）。能连外网时可改 arcgis-imagery（ArcGIS 官方世界影像，免费免 key，带 Esri 署名）或 tianditu（要有免费 tk，开发走仓库自带的 /tianditu.map 代理）。

README.md 7.8 KB Historia Raaka