14: 关联监测设备图层规格（来自决策票 05）

Type: spec Status: ready-for-agent Label: ready-for-agent Blocked by: 05 Category: spec

本规格固化决策票 05的维护者确认结果，作为同一张 map的子规格单。它是关联监测设备图层的实施输入，不覆盖同目录现有的 spec.md；现有 spec.md 继续只描述票 03 的监测点/设备定位视角契约。

进度：100%

规格文档已发布为 ready-for-agent 并挂到同一决策 map；100% 仅指规格交付，不表示关联监测设备图层已实现。下一步：后端契约票 09 明确设备级坐标、校验和状态后，后续实现按本规格接入；票 06/07/10/11 继续裁决视觉、反应、资产与重叠设备细节。未经本对话明确要求，本次不运行 build 或浏览器走查。

（2026-09-24 执行核验通过：对抗式逐条对照票 05 ## Answer 与测试接缝，规格与既有 isRenderable()/deviceCodes 代码事实一致，未覆盖票 03 的 spec.md，未冒称已实现；维持 100%，保持 ready-for-agent 规格发布态，详见 Comments。）

Problem Statement

值班人员从一张图或监测点台账选中一个监测点后，需要看到该监测点关联监测设备的真实空间位置，并能继续使用两级详情和定位。当前默认地图摘要只包含监测点与未关联设备；快照里虽有点位的关联设备编码清单，前端尚未读取。点位详情已有设备自身状态卡片，但缺少设备级坐标与校验，也未接入独立设备图层。若把关联设备直接并入默认摘要，会污染分页、快照和既有图例；若把监测点坐标当作设备坐标，又会制造错误位置。

现有详情接口与地图摘要没有共同的 snapshotAt 锁定，详情还可能复用同点位缓存，因此跨端点数据不能被假设为同一时刻。切换一级模式、刷新快照、分页和坐标失败也必须让值班人员知道对象仍存在、当前为什么没有设备图标，以及哪些数量已经确认。

Solution

从值班人员视角，选中监测点即启动关联监测设备数据加载；监测点自身坐标可用于定位时，同时启动点位定位。确认无地图位置的监测点从台账打开时，展示注明原因的固定详情，不制造相机定位或虚假锚点。有效设备位置返回后，设备显示在一个独立的关联监测设备图层中；默认地图摘要仍只负责监测点和未关联设备。地图入口与监测点台账入口遵守同一套选择规则，设备图层不要求额外点击“展开设备”，也不等待相机飞行停稳。

关联监测设备图层属于当前选中监测点，是临时显示层，不是新的业务对象。设备标记使用独立的设备身份和所属监测点身份，可以被独立拾取；它不冒充监测点，不回写地图摘要，不改变未关联设备的独立标记和直接进入设备详情的行为。

只有当前地图快照确认属于该监测点、且后端发布的设备级坐标通过坐标准入的设备才可上图。坐标缺失、非法、未校验、归属无法确认或设备位置数据失败时，设备仍保留在设备清单中，并显示明确的待确认/不可用原因。不能使用监测点坐标替代设备坐标，也不能人工偏移制造设备位置。

总体概览和运行监测显示所选监测点全部坐标准入有效的关联监测设备；基础设施隐藏该图层；预警处置只显示设备自身状态为报警或预警的关联监测设备。正常、离线、工单处置、未知状态的设备不会因监测点聚合状态而被冒充为报警设备。设备状态未知不妨碍它在总体概览、运行监测依有效坐标显示（具体视觉由票 07 裁决）；在预警处置则暂不上图并归入状态待确认/失败。

User Stories

作为值班人员，我想从地图点击监测点后自动开始加载关联监测设备，以便不用再寻找第二个展开入口。
作为值班人员，我想从监测点台账卡片打开同一个监测点时得到相同的关联设备行为，以便地图入口和台账入口不会产生两套手感。
作为值班人员，我想点选有有效地图位置的监测点后镜头定位和设备加载并行，以便数据较慢时仍能先看到点位位置。
作为值班人员，我想设备位置返回后即可看到设备图标，以便不必等待镜头动画完全停稳。
作为值班人员，我想关联监测设备拥有独立的设备编码和所属监测点身份，以便点到设备时不会误打开另一个监测点。
作为值班人员，我想默认一张图仍以监测点和未关联设备为基础，以便关联设备不会重复计入摘要分页和默认地图标记。
作为值班人员，我想未关联设备继续保持独立标记并可直接进入设备详情，以便没有监测点归属的设备不会被错误归入某个点位。
作为值班人员，我想关闭详情后关联监测设备图层立即消失，但相机停留在当前视角，以便继续观察刚才的区域。
作为值班人员，我想从监测点 A 切换到监测点 B 时立即移除 A 的设备图层，以便不会把 A 的设备误认为属于 B。
作为值班人员，我想切换点位后迟到的 A 数据不会覆盖 B，以便快速巡检时详情和图层始终指向当前选择。
作为值班人员，我想同一地图快照翻页时当前设备图层保持不变，以便分页新增摘要对象不会造成设备图层闪烁或重取。
作为值班人员，我想刷新或快照失效时先撤下旧设备图层，以便旧快照的设备不会被误读为新范围的数据。
作为值班人员，我想新快照第一页没有旧点位时系统保留已取详情、暂隐面板并继续查找后续页，以便渐进加载期间不会错误关闭详情或丢掉正在阅读的内容。
作为值班人员，我想新快照完整加载仍找不到旧点位时看到明确说明，以便知道它已不属于当前筛选范围。
作为值班人员，我想新快照查找失败时看到“待确认”并能重试，以便网络失败不会被误判为点位消失。
作为值班人员，我想台账先选到尚未加载进地图摘要的监测点时仍能打开详情，并在点位坐标有效时定位，以便台账不依赖用户先翻完地图分页；确认无地图位置时仍能阅读注明原因的固定详情。
作为值班人员，我想台账提前选中时先在点位详情和设备清单看到“待当前快照核对”，关联监测设备图层暂不展开，以便详情卡片不会被误当成当前地图位置证据；核对归属并满足坐标准入后才上图。
作为值班人员，我想跨端点数据不同步时看到风险提示，以便知道设备位置可能与当前地图快照不同。
作为值班人员，我想当前快照的设备总数来自该点位去重后的 deviceCodes，以便总数与地图范围保持一致。
作为值班人员，我想设备编码清单尚未加载或缺失时看到待确认，而不是看到一个猜出来的总数。
作为值班人员，我想详情多返回的设备仍能在清单中如实看到，但被标注为与当前地图快照不一致，以便系统不静默丢弃后端信息。
作为值班人员，我想当前快照独有但详情尚未返回的设备显示编码占位和待确认，以便设备不会因详情延迟而被误报为不存在。
作为值班人员，我想没有有效设备坐标的设备仍在设备清单中并显示原因，以便“没有图标”不会被理解成“没有设备”。
作为值班人员，我想系统默认显示所有坐标准入有效的关联监测设备，以便正常设备不会被前端静默过滤。
作为值班人员，我想将来设备数量超过性能预算而需要降级时看到如实的聚合数量和“还有更多”提示，以便不会把未逐台绘制的设备误读为已经上图；具体形态由票 11 决定。
作为值班人员，我想总体概览和运行监测看到所选点位全部有效设备，以便进行完整巡检。
作为值班人员，我想基础设施模式隐藏关联监测设备图层，以便地图只呈现该模式允许的对象范围。
作为值班人员，我想预警处置模式只看到设备自身报警/预警状态的设备，以便异常巡检不会把正常设备画成报警设备。
作为值班人员，我想设备自身状态未知时看到待确认，而不是看到正常、报警或预警的猜测。
作为值班人员，我想总览与分项模式互切时保留选择身份，以便切回总览后可以恢复原来的详情和设备图层。
作为值班人员，我想目标模式不显示所选点位时详情和设备图层暂停，以便模式范围和详情归属不冲突。
作为值班人员，我想三个分项之间切换时清空选择并收起设备图层，以便不同分项不会携带上一分项的空间对象。
作为值班人员，我想一级模式切换不重建地图实例，也不额外换地图快照，以便切换保持一张图的连续性。
作为值班人员，我想默认摘要图例和关联设备图例分开，以便监测点状态不会与设备状态混为一谈。
作为值班人员，我想默认摘要标记数不包含关联设备，以便摘要分页数量、点位图例和设备数量各自有清晰含义。
作为值班人员，我想关联设备计数能区分模式隐藏、实际已上图、明确无地图位置和待确认/失败，以便差额有原因可追溯。
作为值班人员，我想设备状态视觉规则独立于监测点聚合状态，以便设备自身状态不会被点位状态词表错误替代。
作为验收人员，我想从真实地图或台账入口完成完整流程并观察外部结果，以便规格能在驾驶舱整体行为上验收，而不是依赖实现内部结构。

Implementation Decisions

关联监测设备图层是以当前监测点为归属的选中态临时图层。它与默认地图摘要标记计划、分页总数、摘要状态图例和摘要 data-map-markers* 计数分离。
地图摘要继续提供监测点和未关联设备；关联监测设备不写回摘要序列。未关联设备仍使用自己的身份和既有视觉，不参加关联监测设备图层的触发、收场或计数。
地图标记和监测点台账都调用同一监测点选择语义。选中有有效地图位置的监测点时并行执行点位定位和关联设备加载；确认无地图位置时仍可从台账打开注明原因的固定详情，不伪造定位或标记。关闭、换点、刷新和快照重载需要使旧的临时图层与迟到响应失效。
关联设备的领域记录至少需要保留设备编码、所属监测点编码、设备自身状态、设备级经纬度、设备级坐标校验结果，以及缺失或不一致原因。地图服务只接收领域对象，不向组件泄露后端原始字段。
关联总数以当前地图快照中该监测点去重后的 deviceCodes 为准。编码清单未加载或缺失时总数为待确认；点位详情统计和卡片数量不能替代当前快照总数。
当快照清单与详情卡片不一致时，两份数据如实并列：快照独有编码显示设备详情待确认，详情独有编码保留卡片但标记为当前快照不一致且禁止上图；只有同时属于当前快照清单、归属可确认且坐标准入有效的设备才进入显示候选。
设备坐标准入只认后端设备级 coordinateValidation.renderable === true；前端不另算经纬度合法范围，也绝不把后端否决者放行。设备自身经纬度缺失或非有限、无法构成地图位置时仍不上图并如实报数据不可用，不用监测点坐标代替设备坐标，不做人为坐标偏移。
设备默认不按状态或固定前 N 台静默裁剪。当前没有可信的单点位设备数量上限；若实际规模超过性能预算，聚合、重叠呈现和“还有更多”的交互由关联的重叠与模型票继续裁决。
一级模式可见性固定为：总体概览和运行监测显示全部坐标准入有效的关联设备，即使设备自身状态未知也不凭状态隐藏；基础设施隐藏关联监测设备图层；预警处置只显示设备自身状态为 ALARM 或 WARNING 的设备，在此模式中未知设备状态暂不上图并进入状态待确认/失败。
总览与任一分项互切保留选择身份；若目标模式隐藏当前监测点，则暂停详情浮层和关联设备图层，切回且点位仍在当前范围时恢复。三个分项之间互切清空选择。一级模式切换只调整可见性与选择态，不重建地图实例或为切换另取快照。
换新快照时先撤下旧关联设备图层，保留选择身份、详情层级与已取数据；对本应可上图但新标记暂未出现的点位，沿票 12 的锚定规则暂隐详情、顶栏提示待核对并保留关闭入口。后台沿新快照逐页查找点位，第一页没有不能判定不存在；找到同编码有效标记后恢复锚定详情并重新加载设备。若核对到该点但确认无地图位置，则按票 12 展示注明原因的固定详情，不等待虚构的标记。完整加载仍找不到点位才关闭详情并说明原因；查找失败保持待确认、已取数据与顶栏关闭入口，并允许重试。地图摘要仍按分页渐进呈现。查找过程须覆盖本快照已取过的页与后续页，不能只查摘要合并态最近保留的对象；合并态的对象数量护栏不能作为点位不存在的证据。
计数分为两套：默认摘要图例和摘要标记数只计算当前模式实际可见的摘要标记；关联设备独立报告总数、实际已上图、模式隐藏、后端明确无地图位置、位置/状态/绘制待确认或失败。设备图例只统计当前模式实际绘制的设备，各类原因应互斥并能解释已确认的关联总数。
设备标记必须携带独立的设备拾取身份和所属监测点身份，不冒充监测点 pointCode。设备图标的形状、尺寸、贴地方式、设备高亮、状态特效、同坐标多设备展开和模型资产不在本规格中决定。
该规格只定义前端行为契约；后端契约任务需补齐点位关联设备的设备级坐标与校验，并确认设备自身状态来源与编码清单的对应关系。未取得可用位置契约时只能展示设备清单和待确认原因，不能伪造空间位置。

Testing Decisions

最高测试接缝是驾驶舱外壳的外部可观察行为：从真实地图标记或监测点台账选中监测点，观察点位定位、详情、关联监测设备图层、摘要图层、模式切换、刷新、快照查找、计数和关闭结果。验收不读取 Cesium 私有实体、不依赖组件私有变量，也不以两份相同的 JavaScript 输入互比来证明渲染成功。
纯逻辑断言覆盖地图摘要分页与 snapshotAt 生命周期、当前快照 deviceCodes 去重与总数、详情/快照差异分类、坐标准入分类、旧响应丢弃、模式可见性和选择暂停/恢复。断言应只面向这些领域行为和返回状态。
驾驶舱走查覆盖地图入口与台账入口一致、有效点位的相机定位与设备加载并行、确认无地图位置时注明原因的固定详情且不伪造定位、设备位置出现不阻塞定位、关闭和换点收场、同快照翻页不重建设备层、换快照后台逐页查找、完整结束后的关闭、失败时待确认提示，以及总览/分项/预警处置的可见范围。
计数走查必须分别核对摘要标记数、摘要状态图例、关联设备总数、当前模式已上图数、模式隐藏数、明确无地图位置数和待确认/失败数；不得把关联设备计入摘要分页或摘要图例。
回归沿用现有地图摘要、坐标校验、两级详情、真实鼠标点选和相机定位走查的测试先例；设备状态视觉、设备模型、同坐标拾取和特效沿各自下游票的验收契约。规格阶段只写验收契约，不运行 build、dev 或浏览器调试。

Out of Scope

后端关联设备的设备级坐标与坐标校验契约的实际补齐，以及设备自身状态来源的确认；该工作由票 09 负责。
设备图标的具体形状、尺寸、贴地实现、模型资产来源、设备级高亮、状态特效和雾气组合；分别由票 06、07、10 及相关实现票决定。
同坐标或近距离设备的聚合、展开、逐台拾取和超量降级；由票 11 决定。
设施、管线、事件、预警报警等其他地图对象的完整四模式可见矩阵；由同一张 map 的票 13 决定。
默认地图摘要分页机制本身、监测点状态视觉词表、既有未关联设备标记、相机定位数值和两级详情导航基础状态机的重定义。
登录、权限、工单写操作、真实数据全面接线、移动端、竖屏和多屏拼接。
覆盖或改写现有票 03 的定位视角规格；本规格只引用其定位行为。

Further Notes

本规格的唯一决策来源是票 05 的 ## Answer；它把讨论结论转为后续实现可消费的行为契约。
“关联设备不上图”在本规格中只表示不进入默认摘要标记计划；选中监测点后的有效设备可以进入临时图层。无地图位置、待确认和模式隐藏分别有明确原因，不能统称为不存在。
历史只读记录只有 3 条有效关联覆盖 2 个点，不能作为单点设备数量上限；当前规格选择默认全画有效设备，未来性能证据不足时回票 11 裁决。
点位详情与地图摘要当前没有共同快照锁定，因此设备位置风险提示是强制行为。后端未来若提供可核对的同版契约，应在实现规格评审时重新核对本条，不得静默删除提示。
本规格新增为同一决策 map 的子规格单，现有票 03 的 spec.md 保持不变。旧规格的 500 m 是点位级镜头预设；其“所有设备可见”须以设备级坐标准入、当前一级模式范围以及设备实际落在视野中为条件，不能覆盖本规格的不上图规则。设备分布超出视野时按旧规格数值校验口回票 03 复议 500 m，不在本规格私自改镜头数值。
规格发布后，实施票应在关联设备坐标/状态契约完成或明确降级方案后开展。

Comments

规格验收核对

已依据维护者确认的票 05 结论、CONTEXT.md 领域词汇、ADR 0002/0003/0004/0005 和既有地图摘要/坐标/详情走查先例编写。测试接缝已由维护者确认为驾驶舱外壳外部行为加领域纯逻辑断言。本次只发布规格文档，没有修改票 03 的 spec.md，也没有运行 build、dev 或浏览器调试。

执行核验（2026-09-24）

阶段判断：本票无 needs-triage 标签；票面已发布 ready-for-agent 规格、进度 100%，map 任务清单已勾选且 Decisions so far 已有条目，判断处于「已完成规格交付」阶段，不进入实施（实施被票 09 后端契约门控，且本 effort 只产决策/规格）。本次不运行 build、dev 或浏览器走查（AGENTS.md 规则；规格票本就只写验收契约）。
对抗式核验（对照验收标准逐条）：① 交付物＝规格文档，验收标准＝忠实固化票 05 ## Answer、不覆盖票 03 的 spec.md、测试接缝由维护者确认；已逐条对照——图层边界与「关联设备不上图＝不进默认摘要」、地图/台账统一触发与并行、独立设备拾取身份、坐标准入只认 coordinateValidation.renderable === true（与 domain/coordinate.js 既有 isRenderable() 口径一致）、总数以当前快照去重 deviceCodes 为准、快照/详情差异分类（[A,B] vs [B,C]）、关闭/换点/换快照生命周期与迟到响应丢弃、四模式可见性（总览/运行监测全显示、基础设施隐藏、预警处置仅 ALARM/WARNING、未知状态归待确认）、互斥计数与摘要图例分离——全部固化且无冲突。② 已核实 spec.md 内容仍为票 03 的定位视角契约（点位级 500 m / 设备级 150 m），本票未覆盖它。③ Testing Decisions 与维护者确认的「驾驶舱外壳外部行为 + 领域纯逻辑断言」一致，未把内部实现细节写成验收条件。④ 未冒称实现：进度区与 Further Notes 均明确「100% 仅指规格交付」，源代码中 deviceCodes 尚未接线、无设备图层，与票面表述一致。
结论：验收通过，维持 100%；保持 ready-for-agent 发布态（与仓库规格文档发布约定一致，见 spec.md）；map 的 Decisions so far 与任务清单无需改动。本次未修改任何代码。

14-associated-monitoring-device-layer-spec.md 21 KB История Исходник