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: 真实安装位置（无安装资料时）、管道所属设备（仅邻近时）、虚构设备

窨井剖切查看: 以井盖与剖切井筒示意模型查看窨井附近地下管道、监测设备及已有状态；未提供接管关系时仅说明空间邻近，不强行将附近管道接入井筒。 Avoid: 井下实测结构（无资料时）、从附近管道推断接管关系

显示粗度: 为使管道示意模型清晰可辨而放大的可视横截面尺寸，与源数据管径、推算管径分别保留；不代表工程尺寸，也不改变管段路径。 Avoid: 真实管径、用显示尺寸回写业务管径

缺少可靠源/推算管径的3D显示可使用DN160燃气/DN400供水/DN800排水作为可读性占位；以visual-default标记，不是测量、推算管径，不参与插值锚点，也不得回写源数据。排水雨污仅按network_level：0污水、1雨水，旧空值按0；其它等级未知时可使用同一DN800几何占位但保持灰色未分类，不猜颜色。

推算管径: 根据同业、端点完全重合且无分叉的连续链两侧已有管径，按缺失段路径中点距离插值得到的示意尺寸；保留两侧来源，不覆盖源数据或声称实测。 Avoid: 实测管径、默认管径、用推算尺寸证明安装拓扑

虚拟埋深: 为地下可视化明确指定的地表以下距离，不是测量或后端发布的真实管道埋深。当前示意默认：燃气1.5m、供水4m、污水8m、雨水10m；非法排水等级使用8m灰色占位。 Avoid: 实测埋深、真实高程、把类别默认埋深写回后端

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

点位状态: 由后端解析并发布的监测点业务状态，包括正常、预警、报警、处置中工单、离线和无关联设备；前端只渲染，不重算。无关联设备的监测点仍是合法监测点，按其「无关联设备」状态计入监测点总数与状态分布——它只是当前没有挂接设备，不是无效对象。 Avoid: 前端聚合状态、按设备记录自行推导、把无设备点位从监测点统计中剔除

无设备点位: 没有任何关联监测设备的监测点。它是点位状态「无关联设备」的具体对象，计入监测点总数与状态分布，并保留在台账与详情中；类型与片区无法经设备推导时如实显示为未分区/未知，不伪造归属。注意与「未关联设备」方向相反：无设备点位说的是「这个点位下面没有设备」，未关联设备说的是「这台设备没有挂到任何点位下」——两者是同一个「关系为空」的两侧视角，不是同一类对象。 Avoid: 把它当作无效点位或测试残留、按设备数为零就丢弃它、把「无设备点位」与「未关联设备」当成同一类对象、用「无设备」掩盖「设备坐标未校验」这类不同原因

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

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

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

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

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

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

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

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

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

片区: 本项目唯一的空间范围维度，编码 0/1/2 → 城南/城北/太常；空值、乱码与未识别值统一显示为「未分区」。由后端 district 字段提供，统计口径保留数字、页面展示层才映射中文。 Avoid: 责任区域（作为独立概念）、管理机构名冒充片区、前端推断片区归属

责任区域: 「片区」的展示别名，不是独立业务概念；本项目不存在独立的责任区域字段，不用管理单位、权属单位、行业或任何其它字段冒充。 Avoid: 把它当作与片区并存的第二套范围维度

窨井: 第四个正式行业（MANHOLE）的界面显示词；与燃气、供水、排水并列。 Avoid: 井盖（旧显示词，作废）、把它当作独立于 MANHOLE 的新行业

无地图位置: 对象因坐标缺失、非法、未通过校验或超出合法范围而不上图的状态；对象仍保留在列表和详情中，并显示明确原因。坐标能否上图只决定呈现，不决定该对象是否计入统计——坐标未校验的对象仍参与计数、分布与筛选。 Avoid: 默认坐标点、静默隐藏、因坐标未校验就把对象从统计中剔除

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

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

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

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

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

采样时间: 设备数据采集/上报的真实时刻（如设备上报时间、状态更新时间）；前端在设备级指标与详情展示，与“数据时间”（记录创建时间）是不同概念，不混用。 Avoid: 数据时间、把记录创建时间当作采样时刻

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

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

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

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

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

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

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

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

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

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