# 32: 生产环境界面降噪（诊断信息收到底部小字）

**What to build:** 正式环境不要把一大块状态文本压在中央一张图的 3D 场景上。开发期的诊断读数
（配置状态、当前模式、引擎浮标、占位标题与实例提示）在生产形态下收起或退成底部半透明小字；
**用户需要观看的颜色语义（点位状态图例、状态灯、图层控件）必须保留**。

（来源：维护者 2026-09-18 明确要求 —— 「UI 上不需要那么多过于明显的 UI 文本遮盖中央一张图的 3D 场景，
当前的状态信息主要在开发中直观 debug 使用，正式环境中只需要使用半透明小字在底部显示即可，
只有颜色语义等用户需要观看的信息需要在 UI 中体现」。）

Status: resolved
Labels: ready-for-agent

## 依赖与事实

- 诊断读数的现有落点：顶栏配置标签（票 04）、引擎状态浮标（票 21，服务层自绘挂在宿主内）、
  中央图上的「中央一张图」标题 / 图层占位 / 实例提示 / 摘要行（票 02、08、09）。
- 票 09 的点位状态图例（`[data-map-legend]` + 状态灯）是**颜色语义**，本票明确不动它。
- 判定形态不能只靠构建模式：地产现场可能要在生产包里看诊断信息，所以给配置开关 `map.ui.debug`
  （显式布尔值优先，缺省跟随 `import.meta.env.DEV`）。

## 验收

- [x] 生产形态下，中央图上的占位标题、图层占位、实例提示、顶栏配置标签与「当前模式」读数**都不显示**。
- [x] 生产形态下，引擎状态仍在（可观测性不变），但表现为**贴底、无底色、半透明、字号更小**的一行小字。
- [x] 生产形态下**颜色语义保留**：点位状态图例、状态灯、图层控件、归位按钮、范围/行业/视图筛选都在。
- [x] 故障时颜色语义不丢：生产形态下引擎失败时那行小字转淡红。
- [x] 形态可由配置切换（`map.ui.debug`），缺省跟随构建模式：开发构建 = 调试形态，生产构建 = 干净形态。
- [x] 开发形态**完全不变**（票 04/09/21/29 走查依赖的选择器与文案都还在）。
- [x] 有真机走查同时覆盖两种形态。

## 进度：100%

**已完成（2026-09-18）。** 生产构建默认就是干净形态，无需任何配置；要现场调试生产包时把
`map.ui.debug` 写成 `true` 即可。

### 改动

- `services/cockpitConfig.js`：新增 `map.ui = { debug: null }` 归一化（`null` = 跟随构建模式；脏值退回默认并记 issue）。
- `services/mapService.js`：引擎浮标两套样式 —— `STATUS_STYLE`（调试：顶部药丸、有边框底色、11px）
  与 `STATUS_STYLE_QUIET`（生产：贴底 2px、无边框无底色、9.5px、`rgba(186,212,224,.5)`），
  节点带 `data-ui-mode="debug|production"` 供走查与排查；`isUiDebug()` 读配置、缺省回落 `import.meta.env.DEV`。
- `components/MapCanvas.vue`：新增 `uiDebug` prop；生产形态收起 `.map-holo__top`（标题 + 图层占位）、
  `.map-canvas__title`（占位标题）、`.map-holo__hint`（实例提示）；摘要行加 `.is-quiet`（更小更淡），
  **图例与状态灯原样保留**。
- `CockpitShell.vue`：`uiDebug` 计算属性（配置优先、缺省跟随构建模式），据此收起顶栏配置标签与「当前模式」读数，
  并把形态下发给 `MapCanvas`。
- `docs/cockpit-deployment.md` 新增 **2.8 界面形态：开发诊断 vs 生产干净**（两种形态对照表 + 开关写法）。

### 验证证据（`yarn dev` @ 8001，Chrome 152 headless）

- 真机走查 `t32-ui-mode-walkthrough.mjs` → **9/9**（同一 dev server，靠注入配置切换两种形态，不依赖构建模式）：
  - 干净形态：`holoTop/title/hint/configTag/modeReadout` 全为 0；图例 8 行、状态灯 1 个、归位 1 个、视图按钮 2 个、
    范围按钮 4 个**都在**；引擎状态 `data-ui-mode=production`、**贴底 3px、无底色、9.5px、alpha 0.5**；摘要行 `is-quiet`；
  - 调试形态：以上诊断元素全部在位（`uiMode=debug`、顶部药丸、有底色、11px），
    与票 04/09/21/29 走查依赖的选择器一致；
  - 两种形态都能读到引擎状态（形态只改呈现，不改可观测性）；全程无页面级报错。
- 回归：9 个浏览器套件全绿（t01 20/20、t04 9/9、t09 28/28、t21 9/9、t21视图 10/10、t28 7/7、t29 6/6、t30 7/7、t32 9/9）、
  9 个逻辑脚本全通过、`yarn build` exit 0。

### 一个踩到的真 bug（已修）

浮标是在 `setEngineState(record,'booting')` 时创建的，而那一刻**配置还没加载完**（`map.ui.debug` 拿不到），
于是永远走 dev 回落 —— 生产形态失效。修法：`paintEngineState()` 里比对 `data-ui-mode`，
配置到手后的下一次绘制就按当前形态重刷样式（也顺带覆盖了运行期改配置的情形）。

### 顺带修掉的测试问题

`t21-view-modes-walkthrough.mjs` 原来用固定 `sleep(2500)` 等相机到位，在连续跑多个 Chrome 的回归批次里
会误判（单独跑 10/10、批次里 8/10）。改为等 `settled === true`（判据容忍引擎重建空档里的 null），
并把「放到目标点」改成与外壳一致的重试调用 —— 现在批次里稳定 10/10。