City-Lifeline-Cockpit/CONTEXT.md

城市生命线地下管网 Web 驾驶舱

面向沅陵县城市生命线业务的 Vue3 + Three.js + CesiumJS Web 驾驶舱上下文。它先与 UE5 城市生命线驾驶舱并行开发，最终可能替代 UE5 交付路线。

Language

Web 驾驶舱: 承载城市生命线一张图和只读业务模式的独立 Web 前端。 Avoid: UE 驾驶舱、Cesium 地图页面（指完整业务系统时）

一张图: 汇聚基础设施、监测设备、运行信息、风险预警和处置状态的统一三维地理视图。 Avoid: 静态底图、地图大屏（指完整业务视图时）

基础设施: 纳入城市生命线管理的燃气、供水、排水等设施及其管线；设施包括水厂、泵站等承载城市运行能力的对象。 Avoid: 监测设备、智能设备、把设备统称为设施

监测设备: 部署在城市生命线场景中、用于采集设施运行或环境风险数据的带传感器智能设备；它与被监测的基础设施是不同业务对象。 Avoid: 基础设施、设施、监测点（指设备本身时）

监测点: 承载一个或多个监测设备的空间业务对象，拥有自己的编码、名称、类型、坐标和状态；一张图优先以监测点作为可点击地图对象。 Avoid: 设备点位、监测设备（监测点是设备的空间承载对象）

设施点: 承载城市生命线设施的独立空间业务对象，包括管网、泵站、水厂、水源地、用水户等类型（各类型在后端独立成表）；它与监测点同属一张图的可显示对象、同级别，但不计入监测点统计。管线是设施中特殊的一类，以折线几何呈现并后续持久化进场景。 Avoid: 监测点、把设施点并入监测点统计、把聚合 KPI 当设施点

关联监测设备图层: 以当前所选监测点为归属、按一级模式显示其关联监测设备的空间图层；它是显示概念，不是独立业务对象，也不改变未关联设备的身份。 Avoid: 设备点位（指监测设备本身时）、把该图层称为新的监测点

点位状态: 由后端解析并发布的监测点业务状态，包括正常、预警、报警、处置中工单、离线和无关联设备；前端只渲染，不重算。 Avoid: 前端聚合状态、按设备记录自行推导

未关联设备: 未挂接到任何监测点下的监测设备；它以独立对象上地图并参与与监测点相同的全局筛选。它有自身的设备状态（报警/预警/工单处置/正常/离线/状态未发布），状态筛选对未关联设备按其设备状态匹配，不借用监测点聚合状态词表。 Avoid: 把它当作没有状态的设备、用点位状态词表冒充设备状态

状态筛选: 驾驶舱全局筛选条件之一，可多选组合（OR）；对监测点按后端聚合点位状态匹配，对未关联设备按设备状态匹配。它与行业、范围、类型筛选同层级，不是某个面板的局部条件。 Avoid: 单值筛选、把状态筛选限制在某一级模式内、前端自行推导状态

异常点: 预警处置一级模式下可见的监测点子集：至少一台关联监测设备处于预警或报警状态的监测点；判定以设备状态事实为准（当前以 /monitoring/situation 的异常设备回联），不借用监测点聚合状态词表。 Avoid: 把未关联设备当异常点、用监测点聚合状态代替设备状态判定

地图摘要: 后端返回的监测点、未关联设备、管线和基础设施的空间摘要数据；它用于初始化和增量更新一张图，不承载完整详情。 Avoid: 全量列表、前端自行聚合数据

快照: 同一次地图加载使用的后端数据一致性标记；前端用它保证一批点位读取的是同一份数据，刷新时切换到新快照。 Avoid: 时间戳、分页页码（指数据一致性时）

渐进加载: 地图先呈现框架，再按分页批次增加摘要点位的加载方式；前端不等待全部数据返回后才显示地图。 Avoid: 一次性加载、无限加载

点位聚合: 当多个监测点在同一位置或近距离重叠时，地图先显示数量和最高优先级状态的聚合对象，缩放或选择后再展开。 Avoid: 人工坐标偏移、把聚合点当作真实监测点

重叠聚合符号: 同一监测点下多台监测设备坐标相同或极近时，关联监测设备图层以单个聚合符号呈现该批设备，带计数与最高优先级设备状态；交互时才在屏幕层摊开成可逐台点选的环/扇形。摊开是纯渲染层的分离手段，不改变设备真实位置语义。 Avoid: 人工坐标偏移、把展开后的屏幕位置当作设备真实位置

行业筛选: 作用于整个驾驶舱的全局范围条件，包括燃气、供水、排水/雨水/污水和井盖；它不是某个页面内的局部筛选。 Avoid: 分类标签、页面内过滤（指全局范围时）

无地图位置: 对象因坐标缺失、非法、未通过校验或超出合法范围而不上图的状态；对象仍保留在列表和详情中，并显示明确原因。 Avoid: 默认坐标点、静默隐藏

两级详情: 从地图监测点或监测点台账卡片进入：先查看点位摘要和设备卡片，再选择设备卡片后加载完整设备详情。 Avoid: 直接打开完整设备详情、打开管理页面、为台账另开一条详情路径

态势总览: 总体概览一级模式中的跨行业 KPI 二级面板，展示设施底数、监测规模、在线率、当前预警/报警、处置率和近 7 日趋势。 Avoid: 把这块面板也叫做总体概览、把它当成第四个一级模式

监测点台账: 运行监测一级模式中以滚动卡片列出当前筛选范围内监测点的二级面板；点击卡片进入两级详情。 Avoid: 环境监测面板、设备台账、把台账对象当成监测设备

报警—工单闭环读模型: 外部业务系统负责报警关联工单及工单处置，Web 驾驶舱只读取并呈现报警、工单、监测设备和监测点之间的真实关系与状态，不提供工单写操作。 Avoid: 驾驶舱转工单、驾驶舱处置工单

数据时间: 用于说明数据记录形成的时间；本项目首期由后端真实记录的创建时间提供，不等同于物理采样时间、接口响应时间或快照时间。 Avoid: 最近采集时间（当没有可信采样字段时）、更新时间（指接口或服务更新时间）

工单状态: 外部工单流程在驾驶舱中的只读状态，权威编码为 0–7；状态 5 表示已结案，状态 6 表示延期中，状态 7 表示已取消。 Avoid: 前端自定义七态、把状态 6 当作已结案

只读模块: Web 驾驶舱首期的展示与查询边界，包含总体概览、基础设施、运行监测和预警处置；不提供管理端写操作。 Avoid: 管理端、工单处置入口

一级模式: 总体概览、基础设施、运行监测、预警处置四个只读业务场景；用户只在这些场景之间切换。 Avoid: 二级页面、完整路由页面、subview

二级面板: 某个一级模式内同时出现在左右两栏的业务信息区块；它不是独立页面，也不单独占路由。 Avoid: 二级视图、二级路由、subview、把面板当成可切换页面

面板展开状态: 某个二级面板当前是展开还是收起；切换一级模式时恢复为默认展开。 Avoid: 当前二级页面、subview

地面/管线视图: 作用于整个驾驶舱的全局呈现条件，同时改变相机预设和地表/瓦片半透明；管线视图让管线呈现更清楚（相机压低、地表半透明），但不隐藏管线折线图层本身——管线折线在进入系统后的四个一级模式中常驻。 Avoid: 相机模式（只说相机时）、行业筛选、每页各记一份的视图状态、把它当管线层的显隐开关

主场景区: 相机进入后锁定并施加视距雾气的矩形地理范围；由部署配置框定，本部署取甲方框定的沅陵县城范围。 Avoid: 锁区、限位区（指该范围时）

定位: 点击监测点（或面板中的设备）后，把镜头带到该对象并按预设视角看清它的动作；预设视角分点位级/设备级两档，数值由部署配置给，组件不硬编码。 Avoid: 归位（那是回「家」视角的另一动作）、只换中心（那是手动操作时的中心规则）

归位: 一键把镜头带回部署配置的「家」视角（县域级默认视角）；定位不改变它。 Avoid: 定位、回到上一个点位

面板锚点: 当前详情面板在一张图中指向的业务对象视觉标记中心：点位摘要指向监测点，设备详情指向所选监测设备；返回摘要后恢复监测点锚点。标记暂时不可见时，详情可以暂隐，设备与监测点的业务归属仍保持。 Avoid: 相机旋转中心、设备详情仍指向父监测点、将面板锚点变化当作设备归属变化