# 驾驶舱自有静态资产

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

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

## 现有内容

| 文件 | 性质 | 说明 |
| --- | --- | --- |
| `aerial.webp` | **临时占位** | 维护者提供的沅陵影像，仅用于在真底图接入前看整体效果。**无地理配准**，不得据此推断坐标。真底图/瓦片归票 21，接入后本文件可删。 |
| `assets/manifest.json` | 运行时资产清单 | 规格 09 最小子集：语义 key → 路径/hash/状态的唯一权威入口。被 `src/modules/cockpit/domain/runtimeAssets.js` 打包导入（同源），同时随产物发布供核对；组件不得绕过它直接引用 `assets/` 路径。 |
| `assets/icons/*.png` | **正式** | 五枚蓝湖正式切图（brand 品牌标题底板 90×34、layers 网格 15×15、points 水滴 16×15、event 警告三角 24×24、resource 火焰 15×15，均为 2x 位图），`status: formal`，由语义 key 经 manifest 解析后消费。 |
| `assets/icons/blank.svg` | **临时** | 空面板占位图示，设计稿未覆盖，保留原内联几何迁移件，`status: temporary`。 |

## 引用方式

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

```js
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` 供走查断言。

**凭据（已废弃，2026-09-28 免鉴权）**：驾驶舱 REST（`/api/cockpit/v1/**`）与 WebSocket
（`/ws/deviceStatus`）均**不再要求任何凭据**；接口安全由网络层内网隔离保障。
`api.token` / `ws.token` 字段仍可写（兼容旧配置）但会被前端忽略。若个别分区出现 401/403，
只把受影响分区标成「数据不可用」，**不跳登录页、不整页遮罩**（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 |

三种写法的例子：

```jsonc
// 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）里两条：

```dotenv
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）。

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

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

```nginx
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"; }
```

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

### 全局粗糙层

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