<!-- DSH-IDEMPOTENCY-KEY: dom-overlay-migrated -->
# 执行票：地图标记 DOM overlay 渲染（billboard 发糊与底板生硬的结构性解决）

<!-- 迁移自 lanhu-cockpit-asset-replacement 票 20（维护者裁定：DOM overlay 属真实数据接线的渲染层工作，放错地图了） -->


Label: ready-for-agent
Category: frontend-execution

## 来源

维护者在批次 3（lanhu-cockpit-asset-replacement 票 16）第七轮走查后的裁定：**「尝试立票做 DOM」**。billboard 方案经七轮迭代仍有两项引擎级限制无法根除：
① 位图缩到屏显后发糊（Cesium billboard 纹理 LINEAR_MIPMAP_LINEAR，预下采样只能缓解）；
② Cesium label 底板不支持圆角/装饰边框（底板位图方案又因 image/text 互斥导致文字消失，已回退）。

DOM overlay 把标记与标签迁到 UI 同层渲染（CSS 全能力），3D 场景只负责每帧提供窗口坐标——维护者原话「使用和 UI 同一层的渲染模式，使用 3D 算法进行定位」。

## 做了什么（已实施）

- **新增 `services/markerOverlay.js`**：DOM overlay 渲染层——标记 SVG（矢量母版，`--tone` 变量注状态色，实心/镂空双形）+ 真 DOM 标签（圆角底板、青色装饰边、text-overflow、hover title 原生能力）；节点池复用（标记消失隐藏不销毁）；`data-marker-overlay-key/kind/code` + `markerMaster/markerInner/markerAnchor/markerDesaturate` 断言面全挂 DOM 节点。
- **每帧驱动**：`postRender` → `syncMarkerOverlay`（投影 + transform 更新 + 屏外隐藏）；投影走 `createCameraEngine` 返回对象的 `projectPivot`（SceneTransforms 包装，含画布原点修正；首版误用 `instance.engine.projectPivot` 报 TypeError 当场修正）。
- **拾取**：DOM 节点 `pointer-events:auto`，`data-marker-overlay-code/kind` 供点选派发；Canvas 拾取保留给 3D 对象。
- **内层染色**：SVG `<image>` 不能逐像素重染，用 CSS filter 链近似（`brightness → invert → sepia → saturate → hue-rotate` → 浅蓝色调）——与图标使用共识 §4.2「内层去色重染」同一规则的 SVG 媒介实现。
- **接入**：`mapService` 挂载时 `mountMarkerOverlay(record.host)` + `attachOverlayRenderer`（每帧从标记计划现算投影）；失败自动回退 billboard 链路。
- **markerAssets 输出**：`renderMarker` 输出预下采样到屏显尺寸（绕开 billboard mipmap 发虚）——降级路径同样受益。

## 保持不变（契约面）

- 合成计划层 `domain/markerPlan.js`（尺寸/锚点/归属/降饱和逻辑原样复用，overlay 只换渲染媒介）；
- `data-*` 断言面（`markerMaster/markerInner/...` 全部挂到 DOM 节点上）；
- 状态词表、拾取身份、面板联动、四模式可见性。

## 走查结论（浏览器实测，2026-10-15）

- 标记**锐利无糊**（SVG 矢量）、标签**圆角底板 + 装饰边**清晰、hover title 读全；三类点选（监测点/关联设备/未关联设备）镜头联动保持有效；控制台无业务报错。
- billboard → DOM overlay 迁移验证：同一份标记计划输入，两种媒介渲染结果一致（归属/颜色/尺寸/标签文本）。

## 遗留

- 聚合符号（K>1）与设备特效（blink/glow/spin）仍在 billboard 层（Out of Scope）。
- overlay 内层 filter 链是近似（sepia+hue-rotate 到浅蓝），与 billboard 逐像素重染色相有细微差异——维护者走查若不满意可换 SVG mask 精确染色。

## 进度

Status: claimed
Type: task
Blocked by:
Labels: ready-for-agent, wayfinder:task

## Comments


### local — 2026-10-15T02:49:19.248Z
维护者第二轮反馈落地：①内层图标直径 60% → 80%（安全边界核验：圆帽区 ≈0.88 倍宽，80% 外沿距帽缘仍有 15 源像素余量）；断言同步更新（合成计划 38/38）。overlay 与 billboard 降级路径同受益（同一合成计划）。


## Answer