# 监测点定位、面板锚定与设备点位联动（决策地图）

Status: resolved
Labels: wayfinder:map

本 effort 只产出决策，不实现功能。实现票在本图收口后接进 `.scratch/cockpit-shell-panel-layout/issues/` 的 34 之后（与 `.scratch/cockpit-primary-area-guardrails` 同一约定）。维护者指定的实现分支是 `feat/anchor-panel-tracking`（建图当日该工作树仍在 `master`，本地尚未看到该分支），本图先把它要发明的语义锁死。

## Destination

把「点击监测点 → 镜头定位到该点位、能在三维场景里看清它 → 面板锚定跟随该点位、表明归属 → 展开该点位下所有设备点位（坐标图标/模型）→ 面板选设备与三维设备点互相对应 → 设备点位按状态（报警/预警/工单处置/正常/离线）产生特效」这五条交互，锁成 agent 可直接实现、不必再发明语义的契约。

目的地达成的判据：五条交互各有唯一答案且互相自洽 —— 镜头定位的 range 与主场景区限位（`.scratch/cockpit-primary-area-guardrails` 的 02 已 resolved）不打架；关联监测设备的位置与状态使用设备自身的后端数据，色值沿用 `styles/tokens.css` 的语义色，但设备状态视觉契约由 07/10 单独裁决，**不能把 `domain/pointStatus.js` 的监测点聚合状态词表直接当作设备状态**；且与三条既有已锁决策的冲突被显式裁决，不留两套说法：ADR 0008 的三键相机、决策地图票 04 的「选中只换中心、保持 heading/range」、实现票 10 的「关联设备不作为独立地图标记重复渲染」。

## Notes

- Domain：城市生命线 Web 驾驶舱 `/cockpit`。词汇以 `CONTEXT.md` 为准（**监测点**＝承载一个或多个监测设备的空间业务对象；**监测设备**≠基础设施；**点位状态**＝后端解析发布、前端只渲染不重算；**两级详情**；**一张图**）。
- 每次会话先读：`CONTEXT.md`、`docs/adr/0001`–`0008`、`.scratch/cockpit-shell-panel-layout/spec.md`；既有决策与票面 —— `.scratch/web-cockpit-decision-map/issues/04-spring-arm-orbit-pivot.md`、`.scratch/cockpit-shell-panel-layout/issues/03-camera-control-contract.md`、`09-point-status-legend.md`、`10-monitoring-point-detail.md`、`22-cesium-pipeline-rendering.md`、`30-intro-gate-and-view-presets.md`、`34-lightweight-city-massing.md`、`.scratch/cockpit-primary-area-guardrails/issues/02-camera-limit-numeric-contract.md`（已 resolved 的限位数值契约）与其 `07`（雾气规格，open）；代码 —— `src/modules/cockpit/domain/{pointStatus,detailFlow,pointDetail,mapSummary,camera,viewPresets}.js`、`services/{cameraControl,mapService,cesiumEngine,pointPick,cockpitConfig}.js`、`stores/{detailStore,mapStore}.js`、`components/{PointDetailCard,MapCanvas}.vue`、`styles/tokens.css`。
- 本图只产出决策，不实现功能；实现票去向见上（`.scratch/cockpit-shell-panel-layout/issues/` 34 之后）。
- 跨图耦合两处：① 镜头定位必须与 `.scratch/cockpit-primary-area-guardrails` 的限位数值契约（02 resolved）与其进出状态机（03 open）合成；② 设备状态特效与该图 07 的自建 depth 后处理级雾同处一个 `PostProcessStageCollection`，两者要在本图 07 里显式对齐顺序与开关。
- 技能：grilling、domain-modeling、research、prototype。
- 决策票状态词是 wayfinder 自己的 `open`/`claimed`/`resolved`，**不套 triage 五标签**。
- 验收＝可计算部分走纯逻辑断言；手感与观感（锚定跟随、特效）由维护者目视走查。按 `AGENTS.md`，改代码后不自动跑 build/dev/走查。
- 阻塞关系以脚本建的**原生** `Blocked by:` 字段行为准（`verify/build-edges.ps1`，并在同一次运行里校验子票数量＝本 `## 任务清单` 条目数）；正文不写 `Blocked by: #<n>` 这类散文兜底，两者不得并存。

### 已复核的现状事实（2026-09-18 只读复核，各票勿重复推导）

1. **地图对象只有两类**：监测点 + **未关联设备**。`domain/mapSummary.js` 的摘要序列如此，票 08/09/10 的「关联设备从不进入标记计划」是**结构性**保证（`domain/detailFlow.js` 文件头写明）。
2. **点选链路**：`services/pointPick.js`（左键「点一下」与「拖着走」的位移判据）→ `cesiumEngine.pickPointMarkerAt()`（只认带 `pointCode` 的实体，回身份不回实体）→ `mapService.onPointPick()` → `stores/detailStore.js` 的两级详情（`none → point → equipment`）。
3. **相机**：ADR 0008 锁三键分工与阻尼；决策地图票 04 锁「选中对象只换中心、保持 heading/range、取消选中不回退中心、只有左键平移才回退」，`cameraControl.setFocus()` 正是这个语义（`applyViewPreset()` 才能连 hpr 一起换）。当前 range 是**县域级**（票 30 home `pitch −55 / range 12000`），所以「只换中心」到不了「能观察该监测点」。
4. **面板是固定浮层**：`components/PointDetailCard.vue` 在 `CockpitShell.vue` 里作为 `main` 的兄弟浮在左右两栏之间，**不读屏幕坐标**；左右两栏 `z-index:2` 压在满幅地图上（票 07 记录的定位约束）。
5. **设备坐标是契约缺口，缺口在数据模型层而非响应包装**（01 已定位）：设备坐标只挂在 `SourceSmartDevice` 上（`CockpitMapSnapshot.java:105-107`、`CockpitMonitoringDistributionSnapshot.java:166-174`），一旦按点位归集就换成**无坐标**的 `CockpitMonitoringPointDeviceSnapshot`（两条 `SourceMonitoringPoint.devices` 都是它：`CockpitMapSnapshot.java:75`、`CockpitMonitoringDistributionSnapshot.java:107`），`CockpitMonitoringPointDeviceCard` 只是继承了缺失。20 个 `/api/cockpit/v1/` 端点**无一**能在「某点位下所有设备」这一粒度给全经纬度 + 校验 + 状态；`/monitoring/situation` 的 `abnormalEquipment[]` 有坐标但只含异常设备且无 `monitoringPointCode`；带完整坐标的只有 `/equipments/{deviceCode}/archive`（逐台＝N+1）。缺的字段：设备级 `longitude/latitude/coordinateValidation`；要动的类：`CockpitMonitoringPointDeviceSnapshot` → `CockpitMonitoringPointDeviceCard` → `CockpitMonitoringPointStatusResolver.cards()`；**端点不必新增**。Gogs #59 交付的是编码清单而非坐标 —— 「#59 已带坐标而前端漏读」这一设想**可以排除**。
6. **点位摘要已带 `deviceCodes`**（后端 BT-1 / Gogs #59 已交付），所以「某个点位下有哪些设备」不必再靠逐点详情接口；另有 `industry/typeCode/typeName/region`（BT-2 / #60）。01 核实其语义：只在 `map-snapshot` 的 `monitoringPoints[]` 回传（`distribution` 的 marker 没有）、构造链无状态过滤所以**含离线设备**、在分页之前算完所以**不受分页影响**、空值是 `[]` 而非 `null`、源顺序去重未排序。**前端全 `src/` 对它 0 引用**（尚未接线）。
7. **现有监测点状态-视觉只有一张表**：`domain/pointStatus.js`（监测点后端六态 + 「状态未发布」+「未关联设备」，各带色键/形状/文字）；这不是设备自身状态词表。语义色只在 `styles/tokens.css` 声明，服务层从 `.cockpit-shell` 计算样式读出来烘焙进图片。设备视觉契约留给 07/10；引擎里目前**零自定义 shader、零 post-process 级**。
8. **设备级模型资产不存在**（01 复核）：45 个 3D 文件全是建筑/车辆/船只/卫星/人体/道具/倾斜摄影瓦片，唯一设备形状的 glTF 只在 `src/plugins/zoneFreeScene/**` 里以 `oss.icegl.cn` 远程 URL 存在（本地无副本）；`domain/pointStatus.js` 的 `SHAPES` 8 个键全是几何原语，**无任何设备形状**；驾驶舱图标是**内联 SVG data-URL**（不是 canvas 光栅化，与 `devicePixelRatio` 无关）。3D Tiles 那条线是**城市体块**（票 34，示意体块、非实测建筑），与设备模型完全无关。

## 任务清单

- [x] [01: 调研 —— 点位下设备的位置数据来源与三维呈现原语](issues/01-research-device-position-data-and-rendering-primitives.md) — 已 resolved，产物 [`research/device-position-data-and-rendering-primitives.md`](research/device-position-data-and-rendering-primitives.md)。
- [x] [02: 调研 —— 设备状态特效在 Cesium 的可用手段与开销预算](issues/02-research-device-status-effect-mechanisms.md) — 已 resolved，产物 [`research/device-status-effect-mechanisms.md`](research/device-status-effect-mechanisms.md)。
- [x] [03: 镜头「定位到监测点」的视角契约](issues/03-locate-camera-view-contract.md) — 已 resolved：点位级 500 m / 设备级 150 m（`map.locate` 配置可改）、`applyViewPreset` 连 hpr 一起换、中心取实测地形、不设限位例外（`range_max = 12,000 m`）、取消选中不回退、归位不改 home；ADR 0008 原位修订 + 决策地图票 04 同步。
- [x] [04: 监测面板锚定跟随的形态与退化策略](issues/04-panel-anchor-following-form.md) — 已 resolved：贴视觉标记、四向避让、无法贴点则暂隐并保留选择；顶栏留关闭入口；无地图位置固定详情为特例。
- [x] [05: 设备点位图层的触发、生命周期与「关联设备不上图」的裁决](issues/05-device-point-layer-trigger-and-lifecycle.md) — 已 resolved：关联监测设备作为选中态独立图层，默认摘要不上图；生命周期、模式范围、跨端点风险与分开计数已裁决，并同步票 09/10、ADR 0005。
- [x] [06: 面板选设备与三维设备点的对应反应](issues/06-panel-to-scene-device-correspondence.md) — 已 resolved：hover=双侧、选中=外环+放大+引线（连监测点标记中心）、首次进设备级飞 150 m 且设备级内切换只换中心、返回点位级回 500 m、全双向联动且锚点仍跟随监测点、其余设备压暗+缩小（阈值 ≥ 3 台）、独立 `pickDeviceMarkerAt()` 且设备点优先、可断言字段 `data-map-device-picked` / `data-map-panel-selection` / `data-map-device-hovered`；规格已固化为票 15。
- [x] [07: 设备状态特效的视觉语言、门控与并发上限](issues/07-device-status-effect-visual-language.md) — 已 resolved：设备五态（报警/预警/工单处置/正常/离线，无 EMPTY）；报警=扩散脉冲、预警=闪烁、工单=旋转环、**正常/离线无特效**；新建独立 `domain/deviceStatus.js` 平行表并新增 `effect` 维度（不借用点位表，且须修掉 `detailFlow.js` 现有的借用）；随票 05 图层常驻、选中设备强化、关详情随图层消失；超 30 台降级为静态异常标记 + 计数（降级后仍看得出有异常）；沿用雾票已 resolved 的「随雾衰减、不开穿雾例外」，且本票特效走场景内 billboard 不占后处理集合故无排序冲突；新增 `map.effects.*`，缺省 `null` 跟随构建形态；验收=领域断言 + 场景图跨帧快照 + 真实帧差 + 人工走查。
- [x] [08: 原型 —— 锚定面板 + 设备点位 + 状态特效的低精度可反应物](issues/08-prototype-anchor-panel-and-device-effects.md) — 已 resolved：维护者授权真实走查（`yarn dev` @8000）后验收通过。已验证：贴点面板、四向落位、自动飞行、设备特效真在动（跨帧快照违规 0）、正常/离线静态、40 台/23 异常在上限 10 时正确降级且仍留异常标记；真跑另修掉 5 个静态断言抓不到的缺陷（`BillboardCollection` 未入场景就 `add({heightReference})` 抛错致设备图标恒 0、computed 无响应式依赖致徽标永久缓存、控制台过大致四向 no-space、每帧重渲染、自动飞行与 `goHome` 阻尼竞态）。**6 条实现约束已转交**：①点击监测点/设备跳转定位（03/06/15 已锁契约）②锚定窗口复用既有两级「点位摘要」结构（12 的实现输入）③图标须可替换、临时图标不作最终验收（记入 10）④特效需更有科技感、参考图出现监测点级扩散环（记入 07，「监测点要不要有特效」是 07 未裁项）⑤初始地球视图不显示业务点位（记入 13 与 30）⑥遮挡规范改判（已原位修订 04/12）。
- [x] [09: 任务 —— 向后端确认/补齐「点位下设备的坐标与状态」契约](issues/09-task-backend-device-coordinate-contract.md) — 后端本地已实现 Redis 共享同 `snapshotAt` 快照、详情/地图集合及分页对齐；现网坐标校核来源缺失，正式降级为清单-only；推送部署和真实联调仍待维护者执行。
- [x] [10: 设备点位「模型」的口径与资产来源](issues/10-device-model-asset-definition.md) — 已 resolved：本期“模型”定义为可替换的位置符号，不加载真三维设备模型；监测点/监测设备可用同素材并以尺寸区分，按各自状态着色；有效坐标严格结合地形贴地，资产与地形失败均如实降级；未来按设备类型接入 glTF/GLB，规格已固化为 [16](issues/16-device-model-and-asset-spec.md)。
- [x] [11: 重叠设备点位的呈现与拾取](issues/11-overlapping-device-points.md) — 已 resolved：重叠聚合符号 + 展开环/扇形、不用 drillPick、折叠态交互（hover 瞬态/click 粘性）、面板 hover 只弱指向不摊开、图例「聚合呈现 K」口径、K>10 降级（`map.overlap.maxFan`=10）；结论已写回票 11 `## Answer`，规格已固化为 [17](issues/17-overlapping-device-points-spec.md)。
- [x] [12: 监测点详情面板锚定跟随规格](issues/12-panel-anchor-following-spec.md) — 已 resolved：由已确认的 04 固化为独立规格；依赖 04，功能实现仍属后续实现票。
- [x] [16: 设备点位模型与资产来源规格](issues/16-device-model-and-asset-spec.md) — 已发布为 `ready-for-agent` 规格子票，依赖 10；规格交付不表示设备位置符号、正式图片素材或真三维模型已实现。
- [x] [13: 一级模式的一张图图层可见性与选择态矩阵](issues/13-mode-layer-visibility-matrix.md) — 已 resolved：引导态 + 四模式 × 监测点/未关联设备/关联设备图层/设施点/管线折线/事件回联的完整可见矩阵（基础设施＝只设施点+管线；运行监测＝监测点+未关联设备；预警处置＝仅异常点+预警/报警未关联设备；管线折线四模式常驻、管线视图为正交呈现条件；引导态可预取但不显示；设施点数据契约另开、拾取/详情/视觉词表移交设施票；异常点判定只认设备 WARNING/ALARM；异常设备视觉跟票 07 `deviceStatus.js` 词表），结论见票 13 `## Answer`，`CONTEXT.md` 已补「设施点」「异常点」词条。
- [x] [14: 关联监测设备图层规格（来自决策票 05）](issues/14-associated-monitoring-device-layer-spec.md) — 已发布为 `ready-for-agent` 规格子票，依赖 05；文档完成不代表设备图层已实现，现有票 03 的 `spec.md` 不覆盖。
- [x] [15: 面板选设备与三维设备点的对应反应规格（来自决策票 06）](issues/15-panel-device-correspondence-spec.md) — 已发布为 `ready-for-agent` 规格子票，依赖 06；把 hover/选中反应、定位联动、双向联动、弱化、拾取与可断言字段固化为实施输入，不覆盖票 03 的 `spec.md`。
- [x] [17: 重叠设备点位呈现与拾取规格（来自决策票 11）](issues/17-overlapping-device-points-spec.md) — 已发布为 `ready-for-agent` 规格子票，依赖 11；把聚合符号/展开环、折叠态交互、面板接缝、K/N 计数、K>10 降级与可断言字段固化为实施输入，不覆盖票 03 的 `spec.md`。
- [x] [18: 一级模式图层可见性与选择态矩阵规格（来自决策票 13）](issues/18-mode-layer-visibility-spec.md) — 已发布为 `ready-for-agent` 规格子票，依赖 13；把引导态 + 四模式的完整可见矩阵、异常点判定、设施点/管线语义、回联定位、图例随模式与选择态合成为实施输入，测试接缝＝`domain/modeLayerPlan.js` 纯函数 + 外壳走查；不覆盖票 03 的 `spec.md`，不表示设施点/管线/异常点图层已实现。

## Decisions so far

- [重叠设备持续聚合入口修订](issues/11-overlapping-device-points.md) / [对应规格修订](issues/17-overlapping-device-points-spec.md) — 维护者将点子设备后隐藏规则改为：所选设备保持中心可见并接替聚合入口，hover/click 可再次展开切换；固定展开时原聚合符号变暗，名称与计数明确显示。

- [面板锚定规格：维护者复验修订](issues/12-panel-anchor-following-spec.md) / [设备对应规格：复验修订](issues/15-panel-device-correspondence-spec.md) — 点位摘要锚向监测点，设备详情及连接短线锚向所选设备；中心图标保持清晰，状态动画移至外围。旧索引中的“锚点仍跟随监测点”已被本次直接裁定取代；上游票 04 的本地 Markdown 记录已同步。

<!-- 本地图已关闭的决策票索引；一条决策只活在票里。 -->

- [01: 调研 —— 点位下设备的位置数据来源与三维呈现原语](issues/01-research-device-position-data-and-rendering-primitives.md) — 产物 [`research/device-position-data-and-rendering-primitives.md`](research/device-position-data-and-rendering-primitives.md)。**一次拿不到设备坐标，且缺口在数据模型层而非响应包装**：坐标只挂在 `SourceSmartDevice` 上，按点位归集时被换成无坐标的 `CockpitMonitoringPointDeviceSnapshot`（改动点 `…DeviceSnapshot` → `…DeviceCard` → `StatusResolver.cards()`；**端点不必新增**）；「#59 已带坐标而前端漏读」**排除**（#59 给的是编码清单）。`deviceCodes` 可直接用且**不被分页污染**（只在 `map-snapshot` 回传、含离线设备、空值 `[]`、源顺序未排序、前端目前 0 引用）。设备与点位**各存独立经纬度**，关联表只有 `equipment_id/point_id`，后端**无任何相对位置信息**（同井/同杆/高度/朝向 grep 0 命中）也**不保证**两点相等 → 「同坐标重叠」是必须预先处置的可能形态（实际重叠比例未知，已毕业为 [11](issues/11-overlapping-device-points.md)）。呈现原语：三者 GPU 侧都批渲染、都能逐元素拾取，但 `scene.pick` **只回最上层一个**（重叠必须 `drillPick`），且**只有 `PointPrimitive` 不支持 `heightReference`**（Entity 的 `point` 贴地是引擎内部拿无图 billboard 顶替）。仓库**无设备级 glTF/GLB**、`SHAPES` 8 键**无任何设备形状**、驾驶舱图标是内联 SVG data-URL。
- [02: 调研 —— 设备状态特效在 Cesium 的可用手段与开销预算](issues/02-research-device-status-effect-mechanisms.md) — 产物 [`research/device-status-effect-mechanisms.md`](research/device-status-effect-mechanisms.md)。特效首选 **`BillboardCollection` 逐点 `scale`/`color` 动画**（整集合一次 drawElements、逐点脏更新；官方 1 万个静态 266 FPS / 动画 138 FPS，故 200 点仍在安全区），升级路径是自定义 `Primitive` + N 个 `GeometryInstance` + 同一 `Appearance`（逐实例数据走 batch table，**一次 draw call 画 N 个**）；`Entity` + `CallbackProperty` 非常量属性会**每帧销毁并重建 Primitive**（社区实测 25 个≈8 FPS、200 个≈0 FPS），只配 1–3 个聚焦设备；`CustomDataSource` 只是容器；`PostProcessStage` **全屏、无法只影响一个点**；`ParticleSystem` 挂在 `Scene.primitives`、全局、无位置参数、无 pick 路径。与限距雾**可同处一个 `PostProcessStageCollection`，但顺序必须显式定为「先特效、后雾」**（`execute` 顺序＝加入顺序、颜色链式而深度不链式），且两级 `enabled` 要一次原子对齐。色值在 WebGL 路径**一律读不到 CSS 变量**，必须经 `services/mapService.js` 的 `toneColors()` 烘焙（`billboard.image`、`Billboard#color`、`Material` uniform、`ColorGeometryInstanceAttribute`、`BufferPointMaterial.color/outlineColor`、`PostProcessStage.uniforms`、自建 GLSL 常量）；形状仍只来自 `domain/pointStatus.js` 的 `SHAPES`。拾取**只取决于有没有 pickId**（与半透明无关），最易踩的坑是不透明特效即便无 pickId 也会用 `depthOnly` 派生命令挡住背后设备点的拾取 → **特效面片必须走半透明 pass**。10/50/200 的量级是推断（产物里已标注），真数留实现票实测。
- [03: 镜头「定位到监测点」的视角契约](issues/03-locate-camera-view-contract.md) — 定位＝`applyViewPreset` 连 hpr 一起换（缺省 heading 0 / pitch −55 / range 500 m，点位级；设备级 150 m；均 `map.locate` 配置可改）；中心取**实测地形**（椭球 0 会埋进地形、破坏「点位居中」验收）；**不设限位例外**（`range_max = 12,000 m`，guardrails 03 收口锚点，两档均不被夹）；取消选中/关闭**不回退**、换点位直接飞下一个；归位不改 home、无历史栈；全球态点选不进区（已知边界）。ADR 0008 已原位修订（选中监测点→定位视角；非监测点对象与手动三键→只换中心），决策地图票 04 已同步；`CONTEXT.md` 已补「定位/归位」词条。
- [04: 监测面板锚定跟随的形态与退化策略](issues/04-panel-anchor-following-form.md) — 维护者确认**始终贴可见标记**：面板随标记中心移动，不遮图标；只避画布边缘，允许被详情窗遮盖或被屏幕裁切，**仅完全离开画面时隐藏**；保留两级选择、顶栏状态与关闭；仅真正无地图位置的对象用注明原因的固定详情。投影与布局归表现层，关闭不回退镜头。完整口径以子票 `## Answer` 的 R-1～R-4 为准；派生规格见 [12: 监测点详情面板锚定跟随规格](issues/12-panel-anchor-following-spec.md)。
- [12: 监测点详情面板锚定跟随规格](issues/12-panel-anchor-following-spec.md) — 将 04 的贴视觉标记、只避画布边缘、允许裁切/被详情窗遮盖、仅完全离开画面才隐藏、顶栏退出和无地图位置特例固化为独立规格；文档已交付，功能仍待后续实现票验收。
- [05: 设备点位图层的触发、生命周期与「关联设备不上图」的裁决](issues/05-device-point-layer-trigger-and-lifecycle.md) — 关联监测设备默认不进入摘要标记计划，选中监测点后进入独立临时图层；地图/台账入口统一、相机与加载并行，关闭/换点/换快照及跨模式选择态已锁。有效设备坐标和当前快照 `deviceCodes` 是上图与总数前提，跨端点不同版显式提示；摘要与关联设备图例/计数分开。票 09/10 和 ADR 0005 已同步；设施、事件等全图模式矩阵移交[13](issues/13-mode-layer-visibility-matrix.md)；规格已固化为[14](issues/14-associated-monitoring-device-layer-spec.md)，完整取舍见子票 `## Answer`。
- [14: 关联监测设备图层规格](issues/14-associated-monitoring-device-layer-spec.md) — 将 05 的默认摘要边界、选中态图层、四模式可见性、设备坐标准入、快照/详情差异、生命周期和互斥计数固化为 `ready-for-agent` 文档。测试接缝由维护者确认：外壳可观察行为为主、领域纯逻辑为辅；本票只交付规格，不宣称已上图。
- [07: 设备状态特效的视觉语言、门控与并发上限](issues/07-device-status-effect-visual-language.md) — 设备五态（报警/预警/工单处置/正常/离线，**无 EMPTY**——那是点位聚合态专有）各有色键/形状/文字/新增 `effect` 维度。**动效只给需处置的三态**：报警=扩散脉冲、预警=闪烁、工单=旋转环；**正常与离线无特效**（五态全动会淹没画面、丢掉优先级语义；风险记录在案，「正常/离线是否够可辨」交 [08](issues/08-prototype-anchor-panel-and-device-effects.md) 原型校准，不由实现票自行加回动效）。**单一来源**：新建 `domain/deviceStatus.js` 平行表，不 import `pointStatus.js` 的状态词表（只可共用 `SHAPES` 片段），色值仍只从 `tokens.css` 经 `toneColors()` 烘焙；**须修掉既有越界**——`detailFlow.js:12`/`:99-107` 现在正拿**点位**表给**设备**配色配形，即「把设备猜成点位状态」在代码里已经发生；状态未发布落 `UNKNOWN` 不猜 `NORMAL`；未关联设备十字标记保持原样。**门控**：随票 05 图层常驻、选中/定位设备额外强化、关详情随图层消失（无需单独消失逻辑）；动态代价只落在异常设备上（`CallbackProperty(isConstant=false)` 会让按需渲染失效，故不扩展到全部设备）。**并发**：不静默截断（票 02 已核 200 点仍在安全区），超 **30 台**降级为静态异常标记 + 一行「N 台异常」计数，**降级后仍看得出有异常**（不能变成「什么都没画」而被读成没有报警）；阈值交 08 现场定；计数沿用票 05 互斥口径，不混入票 09 八行摘要图例。**与雾**：沿用 `.scratch/cockpit-primary-area-guardrails` 雾票（已 resolved）Answer 第 6 条「随雾衰减、不开穿雾例外」；本票特效走**场景内 billboard** 而非后处理级，故「先特效、后雾」自动成立、**不占** `PostProcessStageCollection`、无排序冲突，也不需要两级原子对齐开关。**降噪**：新增 `map.effects`，缺省 `null` = 跟随构建形态（与票 32 的 `map.ui.debug` 同构）；关特效只关动效，静态色/形/文字仍在位（不破坏「颜色不是唯一线索」）。**可断言**（维护者选 A **+ 人工走查**）：领域纯逻辑断言（映射唯一、未知落 `UNKNOWN`、正常/离线 `effect` 空；**不单独作为验收**，避免恒真断言）+ 场景图快照（同一设备**逐点 `scale`/`color` 跨帧确实变化**，证明「真在跑」而非「已配置」）+ 真实帧差（两帧像素差，顺带补票 02 留下的实测空白）+ 人工走查观感。设备模型口径归 [10](issues/10-device-model-asset-definition.md)、面板联动归 [06](issues/06-panel-to-scene-device-correspondence.md)、重叠设备归 [11](issues/11-overlapping-device-points.md)、其余图层矩阵归 [13](issues/13-mode-layer-visibility-matrix.md)；本票只产决策不实现。
- [06: 面板选设备与三维设备点的对应反应](issues/06-panel-to-scene-device-correspondence.md) — hover＝双侧（面板 hover 卡片 → 三维点轻放大；三维 hover 设备点 → 面板卡片高亮，复用 `detailStore.selectDevice`）、选中＝外环 + 放大 + 引线（连监测点标记中心，随锚点走；重叠时引线退化不画）、首次进设备级飞一次 150 m 且设备级内 A→B 只换中心、返回点位级回 500 m 定位视角（属层级回退，不是票 03 的「取消不回退」）；全双向联动（三维点设备 → 面板滚动 + 进设备级第二级；返回点位还原为监测点选中态；锚点仍跟随监测点标记中心）；其余设备压暗 + 缩小、阈值设备数 ≥ 3 台、hover 只作用于非选中设备（撤弱化 + 轻放大，不叠外环/引线）；新建独立 `pickDeviceMarkerAt()`（认 `deviceCode`，票 05「不冒充监测点」结构性保证）、点选先设备点再监测点（设备点优先、监测点兜底）；可断言字段 `data-map-device-picked` / `data-map-panel-selection`（`none|point|equipment`）/ `data-map-device-hovered`，不破坏既有 `data-map-picked`；重叠拾取归 [11](issues/11-overlapping-device-points.md)。本票只产决策不实现；规格已固化为[15](issues/15-panel-device-correspondence-spec.md)。
- [08: 锚定面板 + 设备点位 + 状态特效的原型](issues/08-prototype-anchor-panel-and-device-effects.md) — 维护者授权真实走查（`yarn dev` @8000）后**验收通过**、票已 resolved。已验证：贴点面板、四向落位、自动飞行、设备特效真在动（场景图跨帧快照违规 0）、正常/离线静态可辨、40 台/23 异常在上限 10 时正确降级且仍留异常标记。**真跑修掉 5 个静态断言抓不到的缺陷**：①`BillboardCollection` 未入场景就 `add({heightReference})` → `DeveloperError: Height reference is not supported without a scene`，设备图标恒 0（Entity 路径不受影响，故「有点位没设备」）②`computed` 读普通 `let` 无响应式依赖 → 徽标永久缓存成「等待引擎」③控制台摊开约 940×180 从下方顶住面板 → 四向 no-space（原型自伤）④每帧无条件写 `layout.value` → 整组件每帧重渲染⑤引导遮罩消失 ≠ `goHome` 阻尼收敛完成（带约 10s 重试）→ 自动飞行被覆盖，改判 `cameraControl.getState().settled`。另记一笔探针教训：`drawImage(canvas)` 读 Cesium 得亮度 0 是 `preserveDrawingBuffer:false` 所致，**不是**画面黑，判断要用截图。**走查产出 6 条实现约束并已转交**：①点击监测点/设备跳转定位（03/06/15 已锁契约）②锚定窗口复用既有两级「点位摘要」结构（12 的实现输入，不得另造层级）③图标须可替换、临时图标不作最终验收（记入 [10](issues/10-device-model-asset-definition.md)，接缝＝`SHAPES`+`markerSvg` 单注入点）④特效需更有科技感（记入 [07](issues/07-device-status-effect-visual-language.md)；参考图出现**监测点级**扩散环，而 07 只裁了设备级——「监测点要不要有自己的特效」是 07 未裁项，实现前须回 07 补裁）⑤初始地球视图不显示业务点位（记入 [13](issues/13-mode-layer-visibility-matrix.md) 问题 5 与 [30](../cockpit-shell-panel-layout/issues/30-intro-gate-and-view-presets.md) 遗留）⑥遮挡规范改判 → 已原位修订 [04](issues/04-panel-anchor-following-form.md)/[12](issues/12-panel-anchor-following-spec.md)。
- [10: 设备点位「模型」的口径与资产来源](issues/10-device-model-asset-definition.md) — 已 resolved：本期“模型”定义为可替换的位置符号，不加载真三维设备模型；监测点/监测设备可用同素材并以尺寸区分，按各自状态着色；有效坐标严格结合地形贴地，资产与地形失败均如实降级；未来按设备类型接入 glTF/GLB，规格已固化为 [16](issues/16-device-model-and-asset-spec.md)。
- [16: 设备点位模型与资产来源规格](issues/16-device-model-and-asset-spec.md) — 已发布为 `ready-for-agent` 规格子票，依赖 10；固化本期位置符号口径、统一可替换资产接缝、地形贴地、按类型渐进真模型、混合显示与透明降级，不表示功能或资产已实现。
- [11: 重叠设备点位的呈现与拾取](issues/11-overlapping-device-points.md) — 已 resolved：静止态＝**重叠聚合符号**（最高优先级状态色/形 + 计数徽标 K），交互态＝**展开环/扇形摊开**（纯渲染层分离，不伪造位置、不参与空间推理，`CONTEXT.md` 人工坐标偏移禁令不动）；**不用 `drillPick`**（靠反复改 `show` 会与票 07 独立开关打架），摊开后普通 `pick` 走票 06 `pickDeviceMarkerAt()` 设备优先链、双向不砍；折叠态交互＝hover 瞬态预览 / click 粘性展开（点设备、点空白、返回点位三条件解除）；**面板 hover 设备卡片只给聚合符号弱指向不摊开**，面板 click 选中卡片才摊开并高亮（摊开绑定持久选中）；**图例「已上图（聚合呈现）K 台」**口径（K＝当前可逐台绘制数，N＝快照去重关联总数，K/N 两数语义固定，三处同源，被聚合不得虚报为逐台上图）；**K>10 降级**（`map.overlap.maxFan` 缺省 10，与票 07 的 30 台特效降级互不影响），降级保持聚合符号 + 显式「K/N」、面板清单保留全部；新增可断言字段 `data-map-overlap-state`（`collapsed|expanded|degraded`）与 `data-map-overlap-count`（＝K）；与票 06/15 边界已写清（引线退化只约束地理重合的未摊开场景，展开态引线照 06 画），票 15 已补边界备注、`CONTEXT.md` 已加「重叠聚合符号」词条。本票只产决策不实现；规格已固化为 [17](issues/17-overlapping-device-points-spec.md)。
- [17: 重叠设备点位呈现与拾取规格](issues/17-overlapping-device-points-spec.md) — 将 11 的聚合符号 + 展开环/扇形、不用 drillPick、折叠态交互（hover 瞬态/click 粘性）、面板 hover 只弱指向不摊开、图例「聚合呈现 K」口径、K>10 降级（`map.overlap.maxFan`=10）与 `data-map-overlap-state`/`data-map-overlap-count` 断言字段固化为 `ready-for-agent` 文档；测试接缝沿用 14/15/16 已确认口径。本票只交付规格，不宣称重叠呈现已实现。
- [13: 一级模式的一张图图层可见性与选择态矩阵](issues/13-mode-layer-visibility-matrix.md) — 已 resolved：完整矩阵＝**引导态 + 四模式** × **监测点 / 未关联设备 / 关联监测设备图层（票 05 已锁）/ 设施点 / 管线折线 / 事件回联**。总体概览＝全部适用对象；基础设施＝只设施点+管线（监测点/未关联设备/关联设备图层隐藏）；运行监测＝全部监测点+未关联设备（设施点隐藏）；预警处置＝仅异常点+预警/报警的未关联设备（异常点＝≥1 台关联设备处于 WARNING/ALARM 的监测点，判定以 `/monitoring/situation` 的 `abnormalEquipment[]` 回联为据，不借用监测点聚合词表）。**管线折线四模式常驻**，「地面/管线视图」为正交的全局呈现条件（只改相机预设与地形/瓦片半透明，不管管线层本身隐藏）；`CONTEXT.md`「管线视图让地下管线可见」据此修订。**引导态可预取但不显示**（标记/图例/计数浮标/详情全部门控，进入后才挂载显示）。**设施点**＝与监测点同级的独立空间对象（管网/泵站/水厂/水源地/用水户等，各类型后端独立成表），数据源＝后端新契约；本票只锁「可见/可回联」，拾取/详情/视觉词表另开设施票。异常设备视觉跟票 07 `deviceStatus.js` 词表（与关联设备图层同表）；图例只统计当前模式实际可见标记、行随模式变。回联定位不做模式过滤（目标在图上则飞、不在则不下发飞行）；基础设施面板回联目标语义＝设施点。选择态合成＝票 05 规则的直接外推（概览↔分项保留身份暂停/恢复、分项↔分项清空；设施点无选择态；切模式不动相机不换快照）。风险：设施点/管线（票 22）/设备状态契约（票 09/#69）未交付 → 本期如实降级；pointStatus 临时视觉未承接（留给票 09/实现票）。`CONTEXT.md` 已补「设施点」「异常点」词条；规格已固化为 [18](issues/18-mode-layer-visibility-spec.md)。
- [18: 一级模式图层可见性与选择态矩阵规格](issues/18-mode-layer-visibility-spec.md) — 已将 13 的完整矩阵、异常点判定（只认设备 WARNING/ALARM、`abnormalEquipment[]` 回联）、设施点/管线语义（设施点与监测点同级、管线四模式常驻、管线视图正交）、回联定位边界、图例随模式与选择态合成固化为 `ready-for-agent` 文档；测试接缝＝`domain/modeLayerPlan.js` 纯函数（浏览器外可断言）+ 外壳人工走查。本票只交付规格，不宣称设施点/管线/异常点图层已实现；设施点拾取/详情/视觉词表另开设施票。

- [09: 向后端确认/补齐「点位下设备的坐标与状态」契约](issues/09-task-backend-device-coordinate-contract.md) — 后端远端已包含同 `snapshotAt` 的 Redis 共享快照与详情/地图分页集合对齐，最终 HEAD `77b4a34`；现网无可信坐标校核源，设备位置清单-only；部署和真实联调待维护者完成。

## Not yet specified

无。运维自检已转交[点位设备联动整体验收与质量收口](../cockpit-shell-panel-layout/issues/48-point-device-linkage-quality-closeout.md)的验收清单。

<!-- 已清：定位契约是否回写 ADR —— 03 已定「原位修订 ADR 0008，不新开 ADR」，已执行。 -->

## Out of scope

- 登录、权限管理、工单处置等写操作（各图已锁）。
- 事件、管线、设施等其他图层的定位与上图：事件定位归实现票 14/19，管线交互优先级归票 22。
- 点位聚合（`.scratch/cockpit-shell-panel-layout` 实现票 09 的遗留，至今不在任何票范围内；本图只在 05/11 里处理「同一监测点下多台设备」这一点点，不接管跨点位聚合）。
- 真实数据接线（后端 BT-5 / Gogs #63 的程序级排期）。
- 重写 `.scratch/cockpit-shell-panel-layout/issues/01`–`34` 的既有实施历史；票 05 经维护者确认后只对票 09/10 补未来口径，并在 ADR 0005 记录模式选择态例外，不追认新图层已交付。
- 竖屏、移动端、多屏拼接（决策地图已判出范围）。
- [锚定面板 + 设备点位 + 状态特效的原型](issues/08-prototype-anchor-panel-and-device-effects.md)曾提出监测点级扩散环，但[设备状态特效的视觉语言、门控与并发上限](issues/07-device-status-effect-visual-language.md)只裁定设备五态特效；本次执行票仅实现设备特效，监测点级扩散环需另行裁决，不由实现代理自行加入。
- 设备模型的美术生产本身（本图只决定口径与资产来源，不制作资产）。

## 进度：100%

已完成：目的地已锁；本图现有 **18 张子票**，其中 **01–13 已 resolved，14–18 已发布为 `ready-for-agent` 规格**。各票结论仍以本地图 Decisions so far 的链接为准；实施已转交 41–48。规格交付不表示设备图层、正式图片素材、设施点、管线或异常点已经上图。

下一步：本决策地图已收口并转交执行；实施入口为 `.scratch/cockpit-shell-panel-layout/issues/41`–`48`，按各票 `Blocked by` 顺序推进。当前最先可做的是[监测点定位与面板锚定接入](../cockpit-shell-panel-layout/issues/41-monitoring-point-locate-and-panel-anchor.md)（仅依赖已完成的区域限位）；后端 #69 已发布但现网设备坐标无可信校核，设备图层必须支持清单-only 降级。真实 Redis/Kingbase 联调和正式设备图片素材仍是后续执行/发布验收事项，不把规格发布当作功能已上图。