18: 一级模式图层可见性与选择态矩阵规格（来自决策票 13）

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

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

进度：100%

规格文档已发布为 ready-for-agent 并挂到同一决策 map；100% 仅指规格交付，不表示设施点、管线折线或异常点图层已实现。下一步：设施点数据契约、管线折线数据源（实现图票 22）、设备级坐标/状态契约（票 09 / 后端 #69）到位后，后续实现按本规格接入；设施点的拾取/详情/视觉词表另开设施票。未经本对话明确要求，本次不运行 build 或浏览器走查。

Problem Statement

值班人员在四个一级模式（总体概览、基础设施、运行监测、预警处置）之间切换时，一张图上的业务对象范围应当随模式变化；当前实现对所有模式画出同一批地图摘要标记，没有任何按模式的可见性规则。问题集中在五个方面：

可见矩阵缺失：总体概览希望展示监测点、设施、预警报警等所有适用对象；基础设施只看设施；运行监测看监测点/设备；预警处置只看异常点。设施与监测设备是不同业务对象，监测点与未关联设备也不得合并为一类。
数据来源缺口：设施点（管网、泵站、水厂、水源地、用水户等，各类型独立成表）当前没有地图坐标数据源；管线折线数据源（票 22）未交付；设备级坐标/状态契约（票 09）未交付。不同图层缺数据时不得伪装成「该模式确实没有对象」。
初始地球视图：进入系统引导的最初地球视图只展示地球整体形态，不展示监测点、设备点位或点位详情；点击「点击进入系统」、镜头落到主场景后，业务点位才出现。
选择态合成：当前选中对象不属于目标模式时的详情暂停与恢复、镜头保持、图例计数和拾取对象优先级，需要与已确认的票 05 规则合成一张完整矩阵。
回联定位边界：事件不创建独立地图标记；设施点在基础设施模式可见并作为回联目标。需要明确各对象「在图上才能定位、不在则不下发飞行」的边界。

Solution

从值班人员视角，一张图在一级模式之间切换时中央地图保持常驻，显示的业务对象集合随模式变化。实现一个统一的「模式图层可见性计划」纯函数模块，作为「什么时候显示什么」的唯一权威；地图引擎和组件只消费该计划，不做第二次过滤判断。五种状态（引导态 + 四个一级模式）与各对象层的完整可见矩阵如下：

状态＼对象	监测点	未关联设备	关联设备图层（选中态）	设施点	管线折线	事件
引导态（进入前）	✗	✗	✗	✗	✗	✗
总体概览	✓ 全部	✓	✓ 全部有效（票 05）	✓	✓	回联定位
基础设施	✗	✗	✗（票 05）	✓	✓	回联定位
运行监测	✓ 全部	✓	✓ 全部有效（票 05）	✗	✓	回联定位
预警处置	仅异常点	仅预警/报警	仅 ALARM/WARNING（票 05）	✗	✓	回联定位

异常点 = 至少一台关联监测设备处于预警或报警状态的监测点；判定以设备状态事实为准（/monitoring/situation 的 abnormalEquipment[] 回联到 point.deviceCodes），不借用监测点聚合状态词表。图例、计数与浮标只统计当前模式实际可见的标记，图例行随模式变化。回联定位不做模式过滤。总体概览与任一分项互切保留选择身份、目标模式不显示当前对象时暂停并恢复；分项之间互切清空选择。引导态可预取地图数据但不显示任何业务点位。

User Stories

作为值班人员，我想在总体概览模式看到全部监测点、未关联设备和设施点，以便一览全貌。
作为值班人员，我想切到基础设施模式后地图只显示设施点与管线，以便专注设施的空间范围。
作为值班人员，我想切到运行监测模式后地图重新显示全部监测点与未关联设备、设施点隐藏，以便专注设备运行侧信息。
作为值班人员，我想切到预警处置模式后地图只显示异常点与预警/报警的未关联设备，以便聚焦待处置对象。
作为值班人员，我想在引导态只看到地球整体形态、没有业务点位，以便先建立空间直觉，不被数据淹没。
作为值班人员，我想点击「进入系统」后业务点位才出现，以便把进入决策作为明确的呈现起点。
作为值班人员，我想引导期可以预先加载地图摘要，以便进入后点位立即呈现而无需长等待。
作为值班人员，我想引导态不显示业务标记、图例、点位计数浮标和详情，以便「没看到对象」不会被误读成「对象不存在」。
作为值班人员，我想一级模式切换不重建地图实例、不换地图摘要快照，以便连续值守有稳定空间上下文。
作为值班人员，我想任一模式的图例只出现该模式可见对象的状态行，以便图例与实际标记保持一致。
作为值班人员，我想数据未就绪的图层如实显示「数据未就绪」，以便缺数据不会被误读成「该模式确实没有对象」。
作为值班人员，我想预警处置模式画出异常点（含预警/报警设备的监测点），以便看清异常的空间分布。
作为值班人员，我想预警/报警的未关联设备在预警处置模式也画出来，以便正在报警的设备不会因没有监测点归属而被漏掉。
作为值班人员，我想正常/离线/工单处置设备不因监测点聚合状态被冒充成异常点，以便颜色语义不被误读。
作为值班人员，我想异常点判定以设备状态事实为准（从 /monitoring/situation 的异常设备回联），以便不借用监测点聚合状态词表。
作为值班人员，我想设备自身状态未知时预警处置模式不猜成正常或报警，以便不掩盖未知。
作为值班人员，我想基础设施模式下已选中的监测点详情与关联设备图层暂停、切回总览且对象仍在当前范围时恢复，以便模式范围与选择归属不冲突。
作为值班人员，我想总览与任一明细模式互切保留选择身份，以便切回总览不丢失正在看的对象。
作为值班人员，我想三个分项模式之间切换清空选择，以便不会把上一分项的对象带到下一分项。
作为值班人员，我想设施点在基础设施模式可见并作为回联目标，以便设施面板条目能定位到图上。
作为值班人员，我想设施数据契约未到位时基础设施地图如实显示「无设施数据」，以便不把缺数据误读成「确实没有设施」。
作为值班人员，我想设施点不进入监测点统计与图例，以便设施与监测点两类对象计数互不污染。
作为值班人员，我想设施点的拾取/交互与视觉词表不在本规格承诺，以便不为不存在的设施详情发明选中态。
作为值班人员，我想管线折线在进入后任何一个一级模式都可见（常驻），以便管线作为设施的一类空间对象持续有用。
作为值班人员，我想地面/管线视图（正交的全局呈现条件）只改相机预设与地表/瓦片半透明、不影响管线层是否显示，以便视图开关不与模式隐藏打架。
作为值班人员，我想事件不创建独立地图标记、而是按设备编码回联到地图位置，以便事件不与监测点标记重复。
作为值班人员，我想事件行所在的设备/监测点可定位，以便从列表条目标到图上对象。
作为值班人员，我想事件设备不在当前地图（未加载/无坐标）时如实提示且不下发飞行，以便不误导为地图上存在该点。
作为值班人员，我想基础设施面板条目的回联目标是设施点，以便切到基础设施模式有图上归属。
作为值班人员，我想设施契约到位前基础设施面板条目的定位如实说明不可定位，以便不把监测点坐标冒充设施位置。
作为验收人员，我想通过外壳可观察行为验证模式切换、图例行变化、引导态门控和回联结果，以便验收外部行为而不依赖 Cesium 私有实体。
作为实施人员，我想只有一个领域纯函数给出「模式 → 标记计划」，以便可见性决策不会在地图与组件两层各裁一遍。

Implementation Decisions

1. 统一「模式图层计划」纯函数矩阵

新建 domain/modeLayerPlan.js（建议名，实施时以契约为准）领域纯函数模块，不 import Cesium / Vue / 接口对象。
输入：{ mode, objects（地图摘要对象集）, abnormalDevices（异常设备集，/monitoring/situation形状）, facilities（设施点集）, pipelines（管线折线计划）, selection（当前选择）, entered（是否已完成引导） }。
输出：{ markers, blocked, legend, locateTargets, degradedNotes }——该模式应显示的标记、被坐标准入拦下的对象、图例行、可回联目标、以及「数据未就绪/无法定位」的如实说明。整个矩阵的裁决在这里收口。
该模块是「什么时候显示什么」的唯一事实源；引擎和组件只消费计划，不在 Cesium 层重新过滤。
纯函数可被浏览器外脚本直接调用断言（仿 verify/t08-map-summary.mjs / t09-point-status.mjs / t21-view-modes.mjs 先例）。

2. 模式可见对象集

总体概览：监测点全部 + 未关联设备 + 关联设备图层（选中态，票 05：全部有效）+ 设施点 + 管线。
基础设施：设施点 + 管线；监测点、未关联设备、关联设备图层不可见。
运行监测：监测点全部 + 未关联设备 + 关联设备图层（全部有效）+ 管线；设施点不可见。
预警处置：仅异常点 + 预警/报警未关联设备 + 关联设备图层仅 ALARM/WARNING（票 05）+ 管线；设施点不可见。
引导态（entered=false）：全部对象不可见；标记、图例、点位计数浮标、详情都不出现。数据可预取但不呈现。
管线折线在四个一级模式常驻；「地面/管线视图」是正交的全局呈现条件，不是本矩阵的显隐开关。

3. 异常点判定

异常点 = 至少一台关联监测设备状态为 WARNING/ALARM 的监测点。
判定源：后端 /monitoring/situation 的 abnormalEquipment[]（设备状态事实）+ 地图摘要 point.deviceCodes（设备 → 监测点归属），把设备状态回联到监测点得到异常点集合。数据源未交付时模块如实降级：不猜、不画。
/monitoring/situation 与 map-snapshot 是不同端点：沿用票 05「尽力展示并明确提示跨端点不同步」，不静默假设两份数据同一时刻。

4. 设施点

设施点 = 与监测点同级的独立空间业务对象（管网、泵站、水厂、水源地、用水户等，各类型在后端独立成表）；不计入监测点统计与图例。
本规格只锁「可见 / 可作为回联目标」；设施点的拾取、详情、视觉词表整体另开设施票，本规格不承诺。
设施数据契约未到位时，基础设施模式地图通过 degradedNotes 如实进入「无设施数据」降级态，不虚报设施行。
设施点的图例行待设施契约与视觉词表到位后由设施票定义。

5. 管线视图正交

管线折线在进入后四个模式均常驻，模式矩阵不隐藏它。
「地面/管线视图」是正交的全局呈现条件：只改相机预设与地表/瓦片半透明（domain/viewModes.js 既有行为），不管管线层本身的显示。
CONTEXT.md「管线视图让地下管线可见」已修订为本语义（「让管线呈现更清楚」，不是层显隐开关）。

6. 事件回联

事件不创建独立地图标记，靠 deviceCode / monitoringPointCode 回联到地图对象位置。
回联定位不做模式过滤：目标在图上（坐标准入且已加载）则按既有定位契约飞行；不在图上则不下发飞行，locateTargets 由模式图层计划给出该模式允许的回联目标。

7. 选择态合成

总体概览 ↔ 任一分项：保留选择身份；目标模式不显示所选项时暂停详情与关联设备图层，切回且对象仍在当前范围时恢复。
分项 ↔ 分项：清空选择。
设施点：本阶段不产生选择态。
切换模式不动镜头、不换地图快照，Viewer 常驻。

8. 图例与计数

图例只统计「当前模式实际可见」的摘要标记；图例行随模式变化。
图例与标记必须一致（沿用票 09 的 legendMatchesMarkers 判据，指向同一计划层输出）。
MapCanvas.vue 的图例列来源改为消费模式图层计划的输出，而不是全场对象视图。

9. 引导态

引导态（进入前）：不显示任何业务点位；点击「进入系统」后才挂载/显示，业务点位才出现。
允许预取：进入前可预取地图摘要，entered=false 时计划输出全部为空；显示层（标记/图例/浮标/详情）被门控。
实现侧进入态挂载归票 30 引导层生命周期；计划层以 entered 输入作门控。

10. 领域词表

CONTEXT.md 已补充「设施点」「异常点」词条并修订「地面/管线视图」（见决策票 13 的 Answer）：设施点与监测点同级不混统计；异常点 = 任一关联设备 WARNING/ALARM 的监测点，以设备状态事实为准。

Testing Decisions

主 seam（已由维护者确认）：domain/modeLayerPlan.js 纯函数是最高接缝，浏览器外逻辑脚本可直接断言；引擎/组件只消费计划，不在 Cesium 层重判可见性。
补充 seam：驾驶舱外壳人工走查，覆盖模式切换观感、图例行变化、引导态门控、管线常驻与回联定位手感。
纯逻辑断言覆盖：五种状态 × 各对象的可见矩阵（含「不该显示的一定不在计划里」）、异常点判定只认 WARNING/ALARM、图例与标记一致、引导态全空、回联目标、降级注释；设施集用注入 mock 断言矩阵逻辑（语义锁死、数据待接线）。
测试先例：沿用 verify/t08-map-summary.mjs（合并态纯逻辑）、t09-point-status.mjs（图例与标记一致）、t21-view-modes.mjs（视图条件纯函数）的断言风格；走查沿用 verify/*-walkthrough.mjs 的 data-* 可断言字段约定。
不把 Cesium 私有实体、组件私有变量或两份相同 JS 输入互比作为成功判据；不做引擎层可见性重判。

Out of Scope

设施点坐标契约、设备级坐标/状态契约（票 09 / 后端 #69）、管线折线数据源（实现图票 22）的实际补齐；后端契约缺失只阻塞实现，不改变本规格的可见性规则。
设施点的拾取、详情、视觉词表与图例行定义（另开设施票）。
设备状态特效、设备模型、重叠拾取等已由票 06/07/10/11 裁决的视觉与交互细节；本规格在其输出范围内引用，不重裁。
位置筛选（如 pointStatus 状态筛选落图、行业/区域筛选）的既有契约与端点；本规格只定义模式可见性。
真实数据全面接线（后端 BT-5 / Gogs #63）。
登录、权限、工单写操作、移动端、竖屏和多屏拼接。
覆盖或改写现有票 03 的定位视角规格与票 05/06/07/10/11 的关联设备图层契约；本规格只在既有契约之上合成模式矩阵。

Further Notes

本规格的唯一决策来源是票 13 的 ## Answer；它把讨论结论转为后续实现可消费的行为契约。
「没有对象」与「数据未就绪」必须分开：EMPTY（后端确实没有）与「设施/设备数据契约未到位」是两种状态，界面与 degradedNotes 都要说得出区别，不能把缺数据伪装成空数据。
管线折线常驻四模式是 2026-09-28 维护者在票 13 的裁决（比「仅基础设施/概览可见」选项更宽）；管线视图的正交语义已同步 CONTEXT.md。
异常点判定依赖设备级状态事实；/monitoring/situation 只含异常设备且与 map-snapshot 跨端点，跨端点不同步提示是强制行为，不得静默删除。
本规格新增为同一决策 map 的子规格单（编号续 14/15/16/17 之后），现有票 03 的 spec.md 保持不变。规格交付不表示设施点/管线/异常点图层已实现。

Comments

规格交付说明（2026-09-28）

本规格由票 13 的 /to-spec 产出，忠实固化维护者确认的完整矩阵与五要素结论。测试接缝（领域纯函数 + 外壳人工走查）已由维护者确认。CONTEXT.md 已同步「设施点」「异常点」「地面/管线视图」三个词条。本次只发布规格文档，没有修改票 03 的 spec.md，没有运行 build、dev 或浏览器调试（AGENTS.md 规则；规格票只写验收契约）。

18-mode-layer-visibility-spec.md 17 KB История Исходник