# 重叠设备点位的呈现与拾取

Type: grilling
Status: resolved
Labels: wayfinder:grilling
Blocked by: 05

## 进度：100%

讨论已完成，维护者已确认 Q1–Q9（两轮 grilling）；`resolved` 表示本票决策完成，不表示重叠聚合呈现或展开环已经实现。实现仍受票 [09](09-task-backend-device-coordinate-contract.md) 的设备级坐标/状态契约或明确降级约束；视觉/反应/资产由票 06/07/10 与 14/15/16 号规格约束。

下一步：本票结论已通过 `/to-spec` 固化为同一张 map 的 [17 号重叠设备点位呈现与拾取规格](17-overlapping-device-points-spec.md)；实现时与 14/15/16 号规格合并消费。

## Question

01 已查明的事实：设备与监测点**各存一份独立经纬度**（`monitor_point` 与 `equipment_base` 各自成列），关联表 `equipment_point_rel` 只有 `equipment_id/point_id` —— 后端**没有任何相对位置信息**（同井/同杆/杆塔/安装高度/朝向 grep 0 命中），且后端**不保证也不校验**设备坐标与点位坐标相等；同时 `CONTEXT.md` 明确禁止「人工坐标偏移」把对象当成真实监测点。

因此「一个监测点下 N 台设备坐标相同或极近」是必须预先设计的**可能形态**；当前无逐台位置样本证明真实重叠比例。若确实同屏重叠，`scene.pick` 只回最上层一个，逐台点选需要额外的呈现/选择策略。

请裁决：

1. **画什么**：N 台完全同坐标时 —— ① 只画一个聚合符号（带计数）？② 按角度扇形摊开（这是**视觉分离**，必须写清它与 `CONTEXT.md`「人工坐标偏移」禁令的边界在哪一句上）？③ 只画状态最高的一台 + 「+N」徽标？④ 根本不画设备点、只用面板清单（若如此，需求②要重新谈）？
2. **拾取**：`drillPick`（01 指出它靠改 `show` 实现、会与特效独立开关互相干扰）？聚合符号点击后**展开**成可选择的环/列表？还是面板 → 三维单向联动（三维不反选，那需求④的双向性要删掉一半）？
3. **与票 06 的分工**：本票定「重叠时画什么、怎么点到具体那一台」；票 06 定「选中后的表现语言」。边界写清楚，别两票各定一半。
4. **计数口径**：聚合符号的计数如何与票 05 的**独立关联设备图例**、关联总数和实际已绘制数量对应？票 09 的八行摘要图例不混入关联设备；票 05 已定默认全画坐标准入有效设备，不默认截前 N 台。
5. **极端量级**：单点位设备台数的真实上限；超过多少台必须降级；降级后如何**如实**表达「还有更多」（不许静默丢，也不许把没画出来的算进「已上图」计数 —— 票 07 的「不上图 ≠ 不存在」同一条纪律）。

## Answer

### 维护者复验修订：聚合入口持续可见（优先于旧收起规则）

维护者确认新流程：监测点显示名称；关联设备聚合符号显示清晰的“聚合 K 台”。hover 高亮入口并瞬态预览，点击固定展开圈且聚合入口半透明暗淡，不直接隐藏。点展开子设备后，真实设备成为中心表层入口，设备详情及连接短线锚向该设备，镜头按设备档定位；设备仍有聚合 hover/click 能力，可再展开并切换同组其他设备。清空选择或返回摘要才恢复无设备身份的聚合符号。

此规则取代“点击子设备收起并隐藏所有设备”及“固定展开隐藏聚合符号”的旧条款。真实设备编码与业务归属不变，只有屏幕呈现和入口变化；不改经纬度、不新增虚构设备。K>maxFan 仍保留总数及清单，选中设备即使来自清单尾部也保证中心可见。旧条款保留为历史。

### 目标与边界

- 本票裁决**同一监测点下多台监测设备坐标相同或极近**时的呈现与拾取；触发前提是票 [05](05-device-point-layer-trigger-and-lifecycle.md) 的关联监测设备图层（选中监测点才加载），本票不重开 05/06/07/10 已锁语义。
- 「重叠」指设备坐标相同或极近到屏幕不可分辨；只处理同一监测点下的设备，不接管跨点位聚合（map Out of scope 已锁）。
- 纪律不变：**不伪造设备真实位置**。聚合符号与展开环是**纯渲染层的呈现/分离手段**——不持久化、不参与空间推理（相机居中、引线长度计算等）、不写进任何「设备真实位置」语义；`CONTEXT.md` 的「人工坐标偏移」禁令对象是伪造数据位置，视觉摊开不触碰它。

### 画什么（Q1）

- **静止态＝一个重叠聚合符号**：取本点可绘制设备中**最高优先级状态**的色/形 + 计数徽标（＝K，口径见下）；与 `CONTEXT.md`「点位聚合」词条同构，但对象是关联监测设备图层（不是摘要监测点）。
- **交互态＝展开环/扇形摊开**：hover/click 聚合符号后，把 K 台设备在屏幕层摊开成可逐台点选的环/扇形（纯渲染层分离，地理坐标不变）。
- 取舍：④（不画设备点只靠面板）被否——直接砍掉需求②；③（只画最高态+徽标）被聚合符号吸收；①+② 组合为最终形态。

### 拾取（Q2）

- **不用 `drillPick`**：[02 调研](../research/device-status-effect-mechanisms.md)已核它靠反复改 `show` 实现，会与票 07 特效/图层生命周期的独立开关互相干扰；摊开后每台设备各有屏幕位置，**普通 `pick` 即可**。
- 展开环内逐台拾取走票 06 的 `pickDeviceMarkerAt()`（认 `deviceCode`）与「设备点优先、监测点兜底」链；三维点设备 → 面板反选成立，**双向性不砍**。
- 聚合符号本身**没有 `deviceCode`，不冒充任何一台设备**；它只承担「打开展开环」这一个动作。

### 折叠态交互模型（Q6）

- 沿用票 06 两档语义：**hover 聚合符号＝瞬态预览**（环/扇形展开、不提交任何选中，离开即收）；**click 聚合符号＝粘性展开**（保持展开，直到「点中某台设备 / 点空白处 / 面板返回点位」才收）。
- 点位在设备图层存在时已处于选中态（票 05），聚合符号 click **不承担选点位**；回点位级走票 06「返回点位」。

### 与面板双向联动的接缝（Q7）

- **面板 hover 设备卡片 → 三维只给聚合符号弱指向（如徽标轻闪/描边），不摊开**；**面板 click 选中卡片 → 才摊开环并高亮/强化那一台**。
- 摊开绑定「持久选中」而非「瞬态 hover」，避免面板扫卡就哗啦摊开；三维侧反选面板在环内点设备后照常成立。

### 与票 06/15 的分工（Q3）

- 沿用[票 15](15-panel-device-correspondence-spec.md)已写死的边界：**引线退化（重叠不画引线）属 06 的选中表现语言；重叠时的 drillPick/展开/逐台拾取归本票**。
- 一条新增接缝：**展开态下引线照票 06 逻辑画**（连监测点标记中心，表达归属）；「重叠引线退化」只约束**未摊开（地理重合）**场景。已补进票 15 边界备注，不重开 06。
- 展开环内选中设备的反应语言（外环+放大+引线）、其余设备弱化（≥3 台压暗缩小）均沿用票 06，不在本票另造。

### 计数口径（Q4/Q8）

- **K＝本点位上「当前可逐台绘制」的设备数**（坐标准入 `coordinateValidation.renderable === true` 且属当前模式）；**N＝关联总数**（当前快照去重 `deviceCodes`）。**两数语义固定，任何地方不出现单个数字冒充全量**。
- 聚合符号徽标＝K；设备图例记 K，但**文案明示「已上图（聚合呈现）K 台」**，不写「逐台上图」——被聚合的设备不得虚报为逐台已上图（票 05/07 纪律）。
- 未进入候选集的（无坐标 / 待确认 / 模式隐藏）单独列原因、不计入 K；面板清单如实列出全部 N 台与未上图原因。
- 降级时（K>10）聚合符号、图例、面板清单**三处同源**：徽标 K、图例「聚合呈现 K」、清单「N 总计 + 原因」；被折叠的 K−10 台在清单中逐台可见，不静默消失。

### 极端量级（Q5）

- **阈值＝10**（维护者定；区别于票 07 特效的 30 台降级，两套机制互不影响）：**K≤10 全量摊开逐台可点；K>10 降级**——不摊开全量，保持聚合符号 + 显式「K 台设备（本屏显示 K 台 / 其余见清单）」形态。
- 阈值放入 `map` 配置域：**`map.overlap.maxFan`，缺省 10**（与 `map.effects.*` 同构）；真数留后续原型/走查现场校准（同 07/08 做法）。
- 降级纪律（票 07 同款）：**不静默丢、不把未逐台画出的算进「已上图」**。

### 可断言口径（Q9）

- 新增只读宿主字段（走票 06 先例，不破坏既有 `data-map-picked` / `data-map-device-picked` / `data-map-panel-selection` / `data-map-device-hovered`）：
  - `data-map-overlap-state` ＝ `collapsed|expanded|degraded`
  - `data-map-overlap-count` ＝ K（当前可逐台绘制数）
- 观感数值（环半径、摊开角度、徽标样式）由实现/原型现场定，不在本票锁死。

### 后续

- 本票只产决策不实现；实现归本图收口后的实现票，与 [14](14-associated-monitoring-device-layer-spec.md)/[15](15-panel-device-correspondence-spec.md)/[16](16-device-model-and-asset-spec.md) 号规格合并消费，前提是票 [09](09-task-backend-device-coordinate-contract.md) 设备级坐标/状态契约或明确降级方案。
- 结论已同步：票 15 补边界备注；`CONTEXT.md` 新增「重叠聚合符号」词条；map 任务清单与 Decisions so far 已更新；规格已由 `/to-spec` 固化为 [17 号重叠设备点位呈现与拾取规格](17-overlapping-device-points-spec.md)。