City-Lifeline-Cockpit/.scratch/cockpit-point-locate-and-device-link/issues/12-panel-anchor-following-spec.md

12: 监测点详情面板锚定跟随规格（来自决策票 04）

Type: spec Status: resolved Blocked by: 04

进度：100%

规格交付已完成并关闭。已对照决策票 04 的 ## Answer、所属 map 的目的地和关联相机契约核验锚点、避让、暂隐与恢复、无地图位置特例及验收边界；此进度仅指文档规格，不代表功能已实现。

2026-09-24 修订：跟随决策票 04 的原位修订，## Solution 顶部新增修订节——不再避让业务 UI、取消 no-space/icon-covered 暂隐、层级低于四个详情窗、唯一隐藏条件是窗口完全离开画面。下方 Implementation Decisions 的旧条款保留以追溯，实现以修订节为准。

下一步：后续实现票按本规格（含修订节）沿驾驶舱外壳验收外部行为；1080p/4K 走查若发现阈值不合适，回票 04 重议。

Problem Statement

值班人员点开监测点的两级详情时，现有卡片固定在两栏之间；转动、平移或定位镜头后，卡片与地图标记的空间归属关系不清楚。标记移出视野或被业务界面遮住时，固定卡片仍在原处，容易让人误以为它属于当前画面里的其他点位。长设备清单还可能压住标记或业务信息。维护者已在本图决策票 04 确认：能看见标记时面板必须贴着它走，不能遮挡图标；确实放不下时可以暂隐，但不得悄悄丢掉正在阅读的详情。

Solution

维护者复验修订：详情按当前对象换锚（优先于旧条款）

维护者明确取代“两级详情均指向监测点”：点位摘要跟随监测点；点击设备点或卡片进入设备详情后，面板及连接短线跟随所选设备视觉标记。设备 A→B 同步换锚，返回摘要恢复监测点锚点；设备的业务归属 pointCode 不变。

锚点包含贴地高度与展开环 pixelOffset；短线接当前尺寸的图标外缘并保留 12 px 间隙。无有效坐标的设备显示注明自身原因的固定详情，不借父监测点坐标；可上图设备标记暂失时暂隐并保留选择。关闭不回退、已有侧栏层级与裁切规则保持。下方旧条款保留为历史，冲突以本节为准。上游决策票 04 的 deck 写入被文件权限拒绝，尚未同步；本节记录本次用户直接裁定。

⚠ 2026-09-24 修订（跟随决策票 04 的原位修订）

维护者在票 08 走查后改变了遮挡规范。以下三条取代下方 Implementation Decisions 中关于避让与暂隐的条款（原文保留以追溯，凡冲突以本节为准）：

1. 不再避让业务 UI：左右业务栏、顶部图例、底部摘要行、无地图位置浮块不再是避让矩形；标记落入这些区域不再触发暂隐。
2. 不再因放不下而暂隐：取消 no-space（四周放不下）与 icon-covered（被 UI 遮住）两种暂隐。面板允许被屏幕裁切。
3. 层级低于四个详情窗：浮动面板在 --z-columns 之下，允许被左右两侧的四个详情窗遮盖。

唯一的隐藏条件：窗口完全离开画面（标记离屏、相机背面/地平线后、投影无效）。这是为了避免「移动到会被详情窗遮住的位置时突然消失」。

仍然不变：始终贴可见标记、四向尝试顺序、不压图标、12 px 间距、卡内滚动、暂隐保留选择与顶栏退出、无地图位置特例、关闭不回退镜头。

实现时 no-space / icon-covered 应移除或标为废弃，不留死代码。

在一张图里打开监测点详情后，面板随所属监测点的可见标记持续移动，细短线指向图标外缘，卡片始终与图标保持可见空隙。两级详情均指向监测点；从地图点开的未关联设备则指向它自己的标记。面板自动在标记四周寻找不挡业务栏、地图信息和图标的位置，长内容在卡内滚动。标记暂时不可见或没有足够空间时，面板暂隐、选择及已取数据保留，顶栏展示对象及暂隐原因并提供关闭；条件恢复时原详情自动重现。确属无地图位置的业务对象仍可由台账打开注明原因的固定详情，不制造假锚点。关闭详情不会让镜头回退。

User Stories

1. 作为值班人员，我想打开监测点摘要后看到卡片指向该点的视觉标记，以便确认卡片属于哪个监测点。
2. 作为值班人员，我想进入该点下某台设备的第二级详情后，卡片仍指向所属监测点，以便在设备内容中保持点位归属。
3. 作为值班人员，我想从地图打开未关联设备时卡片指向设备自己的标记，以便不误以为它属于一个监测点。
4. 作为值班人员，我想看清完整的点位标记和图标形状，以便面板出现时仍能辨识地图状态。
5. 作为值班人员，我想在面板与标记之间看到短的归属指示，以便两者有间距时仍能判断联系。
6. 作为值班人员，我想镜头定位飞行时面板连续跟随标记，以便移动途中不会指错对象。
7. 作为值班人员，我想拖动、旋转或缩放地图时面板持续跟随可见标记，以便当前详情与空间位置保持一致。
8. 作为值班人员，我想面板优先出现在标记右边，空间不足时自动翻到左、下、上方，以便尽量保留可读详情。
9. 作为值班人员，我想面板避开左右业务栏、图例及地图状态信息，以便查看详情不妨碍值守信息。
10. 作为值班人员，我想长设备清单和设备详情在卡片内部滚动，以便标题、关闭入口和地图标记仍可见。
11. 作为值班人员，我想标记移出屏幕、落到地平线后或相机背后时卡片暂隐，以便画面不留下失去归属的详情。
12. 作为值班人员，我想标记被左右栏或图例盖住时卡片暂隐，以便看不到锚点时不会误认卡片归属。
13. 作为值班人员，我想四周都放不下可读面板时暂隐卡片，以便面板不强行压住业务信息。
14. 作为值班人员，我想卡片暂隐期间仍保留当前监测点、设备层级和已加载数据，以便回到视野时接着阅读。
15. 作为值班人员，我想卡片暂隐后自动在标记重现时恢复，以便不必再次点选或重新请求详情。
16. 作为值班人员，我想暂隐时在顶栏看到对象名称或编码和原因，以便知道当前仍有一个详情选择。
17. 作为值班人员，我想从顶栏状态入口关闭暂隐的详情，以便标记长期缺失时仍能退出选择。
18. 作为值班人员，我想只在标记仍有效时使用重新定位入口，以便不会对已经不存在的标记触发无效定位。
19. 作为值班人员，我想换快照后同一编码的标记重现时恢复原详情，以便数据刷新不中断阅读。
20. 作为值班人员，我想新快照尚未查完、标记暂时未出现时保留选择并能主动关闭，以便渐进加载期间仍可退出；快照完整查完仍无该点时按票 05 关闭详情。
21. 作为值班人员，我想体块遮住地表但视觉标记仍显示时继续看到贴点卡片，以便卡片行为与眼前标记一致。
22. 作为值班人员，我想从台账打开无地图位置的监测点时仍能读到注明原因的固定详情，以便坐标问题不剥夺业务信息。
23. 作为值班人员，我想关闭详情后卡片与短线消失而镜头留在当前视角，以便继续观察刚才的区域。
24. 作为验收人员，我想在 1080p 与 4K 画布下观察面板避让、滚动和暂隐，以便确认空间阈值与跟随手感可用。

Implementation Decisions

2026-09-24 修订标注：以下第 3、5 条关于「避让业务 UI 矩形」与「暂隐」的条款已被 ## Solution 顶部的修订节取代，实现时以修订节为准（不再避让业务 UI；取消 no-space/icon-covered；层级低于四个详情窗；只在窗口完全离开画面时隐藏）。第 1、2、4、6 条仍然有效。

• 面板锚点是可见的贴地视觉标记中心，不是椭球高度零的经纬度投影点，也不是图标顶部或相机旋转中心。卡片边缘距 18×18 CSS px 图标外缘至少 12 CSS px；短线只连接到图标外缘，不能覆盖图标。两级详情均以监测点编码解析当前标记；未关联设备以设备自身标记为锚。
• 使用 Cesium 世界坐标投影并换算到窗口坐标，明确处理标记坐标缺失、投影无效或非有限、相机背面、地球背面/地平线后、画布外及标记被业务 UI 覆盖。可见性遵从实际视觉标记；当前标记忽略深度遮挡，故地表被 3D Tiles 挡住而标记仍可见时继续显示卡片。无需独立的相机矩阵手算投影或以体块地表深度作另一个隐藏判据。
• 运行时获取地图画布、左右栏、顶部图例与调试抬头、底部摘要与引擎状态、无地图位置浮块以及图标的实际矩形。候选面板先右后左再下、上；侧边可沿垂直方向调整，但连线继续指向原标记。候选矩形不得与保护区或图标相交（← 已取代：不再避让业务 UI），画布边缘约留 12 CSS px，不能凭固定屏幕坐标猜测。仍不得压住图标。
• 面板宽 300–420 CSS px；高度不超过扣除保护区后地图画布可用屏幕高度的 80%，也受当前候选位置实际剩余高度限制。低于约 280 CSS px 可读高度时暂隐（← 已取代：允许被裁切，不再因此隐藏）。标题与关闭入口保持在卡内，设备卡片与设备详情正文在卡内滚动；屏幕可用高度不等于领域词汇“主场景区”的地理范围。
• 有可用标记却暂时不能可靠投影或安放面板时，只改变表现可见性，保留监测点与设备两级选择、已取数据和在途请求的既有语义；不拿上一帧的卡片位置充数。重入视野和布局变化后自动恢复原详情。暂隐顶栏入口显示名称或编码与原因并可关闭；仅标记有效时可重新定位。标记在新快照分页期间暂时消失时通过编码等待新标记，不保存旧引擎实体；查找失败保留待确认与关闭入口，完整加载确认该点不在当前范围时依票 05 关闭详情。
• 确认无地图位置的监测点从台账打开固定详情并如实说明原因。这是无有效锚点业务对象的特例；可上图标记因视角、快照或布局暂时不可用时仍按暂隐处理，不转为固定卡片。没有有效坐标的设备不上图。
• 定位飞行及手动平移、旋转、滚轮期间，对当前单个锚点随已渲染画面更新投影与布局，每帧最多一次；无详情、页面不可见、镜头稳定且布局未变时停止计算，恢复或尺寸变化时立即重新计算。
• 地图服务提供只读标记位置、投影和可见性查询；详情面板与外壳管理临时布局、顶栏暂隐反馈。保留现有两级导航状态与详情选择语义，不把帧坐标写入业务 store。关闭详情收回卡片与指示、清除详情选择，但不回退相机，遵循 ADR 0008。地图点选的镜头行为应服从本图票 03 已锁的实测地形中心与完整预设视角，不能把当前只换中心且高度零的代码现状当作目标。

Testing Decisions

• 主要测试接缝沿用驾驶舱外壳的外部可观察行为：从地图真实点选或台账打开详情，观察卡片、图标、短线和顶栏入口；操作相机与刷新快照后断言归属、可见性、层级及关闭结果。不以内部投影函数或组件私有变量作为验收条件。
• 几何边界可用少量纯逻辑断言覆盖四向候选顺序、矩形交集、图标间距、宽高上限和无法容纳的暂隐结果；实际贴地高度、地平线、UI 遮挡、相机飞行手感与 1080p/4K 的可读性需要真实画面走查。先复用现有点位详情的真实鼠标走查与相机契约走查方式；不新增一套测试框架。
• 验证两级详情与未关联设备锚点、无地图位置特例、关闭后相机不回退；标记从可见到屏外/背面/UI 遮挡/无空间再恢复；换快照同编码重关联和查找失败时的顶栏退出、完整查找后不存在则关闭；体块只挡地表时仍贴可见标记。只断言外部结果和数据不重复加载，不要求特定内部帧循环实现。
• 本规格是文档产物，本次不改代码；按项目规则，本次不启动 build、dev 或浏览器调试。实现后的 4K 帧耗与体验由实现票走查，若阈值不合适应回到决策票 04 重议，不能自行把“始终贴点 / 不可贴则暂隐”改成固定面板。

Out of Scope

• 关联监测设备图层的触发、生命周期与摘要语义，归本图票 05。
• 面板与三维设备点的双向联动、设备级高亮与定位反应，归票 06；本规格仅规定详情面板的归属锚点。
• 设备状态特效及其与雾的组合归票 07；组合手感与视觉原型归票 08。
• 设备级坐标的后端补齐、设备模型资产、同坐标设备的拾取，分别归票 09/10/11。
• 非监测点和未关联设备的镜头定位数值、其他图层，以及竖屏、移动端与多屏拼接。

Further Notes

• 上游决策源是本图票 04 的 ## Answer；“面板锚点”沿用领域词汇，不与 ADR 0008 的相机旋转中心混用。票 03 的定位规格已有同目录 spec.md，本票是独立规格子票，不覆盖它。
• 此规格以当前已有的详情内容和驾驶舱外壳为基础。现有详情仍固定摆放，投影只在开发态相机把手处可用；实现需要接出正式只读的视觉标记查询与布局状态。规格完成不表示功能已经实现。

Answer

将决策票 04 的「始终贴可见标记；贴不下则暂隐、不退回固定位置」固化为可实施与验收的规格：两级监测点详情共用监测点视觉标记锚点，未关联设备锚向自身标记；按右、左、下、上及实际保护区避让，不能可靠显示时保留选择与已取数据，顶栏提供状态与关闭入口，条件恢复后自动重现。无地图位置对象的固定详情仅作注明原因的特例；关闭不回退相机。几何边界走纯逻辑断言，实际贴点与 1080p/4K 手感留后续实现票目视验收。

Comments

规格验收核对

已核对上游决策票 04 的五轮维护者确认和 ## Answer；本票没有 needs-triage 阶段，依赖 04 已 resolved。核对 ADR 0008、CONTEXT.md 与现有 PointDetailCard.vue / mapService.js：领域术语与关闭不回退契约一致，当前实现仍是固定面板，规格没有冒称功能落地。此处仅静态核对文档与源码；项目规则禁止未经明确要求运行 build/dev 或浏览器走查。