docs(cockpit): 领域词汇、ADR 0001-0008 与并行 Web 驾驶舱规格

CONTEXT.md

@@ -0,0 +1,85 @@
+# 城市生命线地下管网 Web 驾驶舱
+
+面向沅陵县城市生命线业务的 Vue3 + Three.js + CesiumJS Web 驾驶舱上下文。它先与 UE5 城市生命线驾驶舱并行开发，最终可能替代 UE5 交付路线。
+
+## Language
+
+**Web 驾驶舱**:
+承载城市生命线一张图和只读业务模式的独立 Web 前端。
+_Avoid_: UE 驾驶舱、Cesium 地图页面（指完整业务系统时）
+
+**一张图**:
+汇聚基础设施、监测设备、运行信息、风险预警和处置状态的统一三维地理视图。
+_Avoid_: 静态底图、地图大屏（指完整业务视图时）
+
+**基础设施**:
+纳入城市生命线管理的燃气、供水、排水等设施及其管线；设施包括水厂、泵站等承载城市运行能力的对象。
+_Avoid_: 监测设备、智能设备、把设备统称为设施
+
+**监测设备**:
+部署在城市生命线场景中、用于采集设施运行或环境风险数据的带传感器智能设备；它与被监测的基础设施是不同业务对象。
+_Avoid_: 基础设施、设施、监测点（指设备本身时）
+
+**监测点**:
+承载一个或多个监测设备的空间业务对象，拥有自己的编码、名称、类型、坐标和状态；一张图优先以监测点作为可点击地图对象。
+_Avoid_: 设备点位、监测设备（监测点是设备的空间承载对象）
+
+**点位状态**:
+由后端解析并发布的监测点业务状态，包括正常、预警、报警、处置中工单、离线和无关联设备；前端只渲染，不重算。
+_Avoid_: 前端聚合状态、按设备记录自行推导
+
+**地图摘要**:
+后端返回的监测点、未关联设备、管线和基础设施的空间摘要数据；它用于初始化和增量更新一张图，不承载完整详情。
+_Avoid_: 全量列表、前端自行聚合数据
+
+**快照**:
+同一次地图加载使用的后端数据一致性标记；前端用它保证一批点位读取的是同一份数据，刷新时切换到新快照。
+_Avoid_: 时间戳、分页页码（指数据一致性时）
+
+**渐进加载**:
+地图先呈现框架，再按分页批次增加摘要点位的加载方式；前端不等待全部数据返回后才显示地图。
+_Avoid_: 一次性加载、无限加载
+
+**点位聚合**:
+当多个监测点在同一位置或近距离重叠时，地图先显示数量和最高优先级状态的聚合对象，缩放或选择后再展开。
+_Avoid_: 人工坐标偏移、把聚合点当作真实监测点
+
+**行业筛选**:
+作用于整个驾驶舱的全局范围条件，包括燃气、供水、排水/雨水/污水和井盖；它不是某个页面内的局部筛选。
+_Avoid_: 分类标签、页面内过滤（指全局范围时）
+
+**无地图位置**:
+对象因坐标缺失、非法、未通过校验或超出合法范围而不上图的状态；对象仍保留在列表和详情中，并显示明确原因。
+_Avoid_: 默认坐标点、静默隐藏
+
+**两级详情**:
+从地图监测点或监测点台账卡片进入：先查看点位摘要和设备卡片，再选择设备卡片后加载完整设备详情。
+_Avoid_: 直接打开完整设备详情、打开管理页面、为台账另开一条详情路径
+
+**态势总览**:
+总体概览一级模式中的跨行业 KPI 二级面板，展示设施底数、监测规模、在线率、当前预警/报警、处置率和近 7 日趋势。
+_Avoid_: 把这块面板也叫做总体概览、把它当成第四个一级模式
+
+**监测点台账**:
+运行监测一级模式中以滚动卡片列出当前筛选范围内监测点的二级面板；点击卡片进入两级详情。
+_Avoid_: 环境监测面板、设备台账、把台账对象当成监测设备
+
+**只读模块**:
+Web 驾驶舱首期的展示与查询边界，包含总体概览、基础设施、运行监测和预警处置；不提供管理端写操作。
+_Avoid_: 管理端、工单处置入口
+
+**一级模式**:
+总体概览、基础设施、运行监测、预警处置四个只读业务场景；用户只在这些场景之间切换。
+_Avoid_: 二级页面、完整路由页面、subview
+
+**二级面板**:
+某个一级模式内同时出现在左右两栏的业务信息区块；它不是独立页面，也不单独占路由。
+_Avoid_: 二级视图、二级路由、subview、把面板当成可切换页面
+
+**面板展开状态**:
+某个二级面板当前是展开还是收起；切换一级模式时恢复为默认展开。
+_Avoid_: 当前二级页面、subview
+
+**地面/管线视图**:
+作用于整个驾驶舱的全局视图条件，同时改变相机预设和图层可见性；管线视图让地下管线可见并把地表压成半透明。
+_Avoid_: 相机模式（只说相机时）、行业筛选、每页各记一份的视图状态

docs/adr/0001-parallel-web-cockpit-baseline.md

@@ -0,0 +1,18 @@
+---
+status: accepted
+---
+
+# Parallel Web cockpit baseline
+
+沅陵县城市生命线驾驶舱先建立独立 Web 前端工程，与 UE5 驾驶舱并行开发，最终可能替代 UE5。首期覆盖一张图和总体概览、基础设施、运行监测、预警处置四个只读模块，不提供管理端写操作；复用现有驾驶舱专用只读接口契约和后端解析的点位状态。
+
+技术栈采用 Vue3 + Three.js + CesiumJS。Cesium 负责地理空间地图、瓦片、3D Tiles 和空间交互；Three.js 负责管线三维表现、构件增强和特写效果。后端统一发布 WGS84(EPSG:4326)，前端只消费发布坐标，不做原始管网数据转换；管网空间数据由用户另行处理并导入数据库。
+
+工程基座沿用当前前端开源项目的技术栈，并新增 CesiumJS。UI 语义沿用 UE 驾驶舱：中央一张图常驻，总体概览、基础设施、运行监测、预警处置四个业务模式切换，行业作为全局筛选，地面/管线作为全局视图条件（同时驱动相机预设与图层可见性）。首期地理底图优先使用天地图，正式交付优先使用甲方提供的本地瓦片、地形、3D Tiles 或模型。管线首期以 Cesium 地理管线为主，Three.js 只用于重点管线、交叉点或构件的增强表达。首期验收优先 3840x2160 横向 16:9，兼容 1920x1080。
+
+后端接入沿用 UE 驾驶舱策略：专用只读接口、部署层注入凭据、`/ws/deviceStatus` 推送、失败分区独立展示。四个只读模块按 UE 现有信息结构重新实现为 Vue/Cesium 页面，不复制 UE 视觉实现。
+
+## Considered Options
+
+- 不把首期开发放入当前 TvT.js 仓库或做成 TvT 插件；当前仓库只作为 Vue3、Three.js 组件和工程参考。
+- 不使用 BD09 或原始 CAD 坐标作为系统基准；BD09 只用于百度地图展示，原始施工图坐标在入库前完成转换和校验。

docs/adr/0002-web-map-data-and-ui-priority.md

@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# Web map data and UI priority
+
+Web 驾驶舱复用后端只读地图契约：地图摘要分页加载，默认每页 500、最大 1000，同一快照使用相同 `snapshotAt`；点位状态由后端解析，前端不重算。地图优先展示监测点，点击后按监测点摘要和设备卡片的两级详情加载。无坐标、非法坐标或未通过校验的对象不上图，但保留在列表和详情中并显示明确原因。
+
+状态更新以 WebSocket 优先，失败时按 3–10 分钟可配置周期轮询，并保留手动刷新。同一位置多个监测点使用地图聚合，不做人工坐标偏移。行业筛选覆盖燃气、供水、排水/雨水/污水和井盖；环境监测设备归入排水。
+
+首期模块顺序为：一张图、总体概览、基础设施、运行监测、预警处置。

docs/adr/0003-web-page-information-architecture.md

@@ -0,0 +1,24 @@
+---
+status: accepted
+---
+
+# Web page information architecture
+
+Web 驾驶舱的一级模式为总体概览、基础设施、运行监测、预警处置。切换一级模式时，中央一张图保持常驻；模式内的全部二级面板同时出现在左右两栏，不再使用 `subview` 或独立二级路由。
+
+布局采用 A 四面板总览方案：顶栏 + 一级模式 + 左右各两块二级面板 + 中央一张图。四个一级模式都固定 4 个二级面板。总体概览为态势总览、基础设施、运行监测、预警设置；基础设施为基础档案、运行信息、管理信息、应急保障；运行监测为监测概览、监测分布、运行概况、监测点台账；预警处置为当前预警、历史分析、预警效率、预警分析。不把环境监测升格为二级面板。每个二级面板通过标题栏展开/收起；切换一级模式时重置为默认展开。同步实现 9 个共享地图/详情视图和 5 个预警/报警模式变体。首期视觉沿用深色指挥大屏、深中性背景和青色强调色；正式视觉资源由设计公司后续交付后替换。
+
+模式与面板使用稳定英文键，中文只用于展示：
+
+| 一级模式 `mode` | 左栏上 | 左栏下 | 右栏上 | 右栏下 |
+| --- | --- | --- | --- | --- |
+| `overview` | `situationSummary` | `infrastructureSummary` | `monitoringSummary` | `alertSettings` |
+| `infrastructure` | `archive` | `operation` | `management` | `emergency` |
+| `monitoring` | `monitoringOverview` | `monitoringDistribution` | `operationOverview` | `monitoringPointLedger` |
+| `warningResponse` | `currentEvents` | `historyAnalysis` | `responseEfficiency` | `eventAnalysis` |
+
+`panelId` 扁平且全局唯一，不带模式前缀；`expandedPanelIds` 即 `panelId` 字符串集合。中文标题由独立的 `panelLabels` 映射按 `panelId` 解析，业务逻辑不读中文。
+
+加载、成功、空数据、字段缺失、数据过期、数据不可用、请求失败、无坐标等状态均为首期正式状态；详情分区必须能独立失败，不使用整页错误遮罩。当前事件列表默认 10-15 条，历史列表提供 7/30/90 天和自定义时间范围。工单只读展示七态：待派单、待接单、已接单、处理中、待验收、已结案、已取消；验收驳回表现为“待验收回退处理中”的动作轨迹，不展示延期。
+
+UI 组件优先沿用当前 TvT.js 前端项目已有组件生态，首期 Fes Design / Naive UI；后续可按大屏定制需要调整，但不应为此重做页面信息架构。

docs/adr/0004-web-rendering-and-state-boundaries.md

@@ -0,0 +1,19 @@
+---
+status: accepted
+---
+
+# Web rendering and state boundaries
+
+Web 驾驶舱采用“Cesium 为主、Three.js 为增强”的分层方案。Cesium 负责地理坐标下的底图、地形、3D Tiles、全市管线、监测点、未关联设备和空间交互；Three.js 只用于重点管线、接头、阀门、断面、局部构件和面板内可视化，不接管 Cesium 场景。两者通过领域状态和选中对象联动。
+
+本地 TvT.js 案例表明 Three.js 适合自定义材质、Shader、3D Tiles 特写和局部增强；官方 `gisPlaneEditor` 文档则强调地图底座、影像地形、贴地表达和 GIS 交互。因此全市管线主图交给 Cesium，复杂空间处理不交给 Three.js。
+
+状态管理使用 Pinia，按领域拆分：
+
+- `mapStore`：地图摘要、分页快照、已加载点位、未关联设备、选中对象、图层可见性。
+- `filterStore`：行业、区域、状态和地面/管线视图。一级模式不属于筛选。地面/管线视图是全局视图条件，同时驱动相机预设与图层可见性（管线视图把地形与 3D Tiles 压成半透明），全局共用且切一级模式不重置。
+- `detailStore`：监测点摘要、设备卡片、设备详情及各分区状态。
+- `runtimeStore`：WebSocket、最后成功刷新时间、手动刷新、过期状态。
+- `uiStore`：当前一级模式 `mode`、面板展开集合 `expandedPanelIds`、返回路径、滚动位置、当前标签页。切换一级模式时重置展开集合，不重置行业筛选。
+
+接口和 WebSocket 统一走 service 层；页面组件只消费领域状态，不直接持有接口字段或连接推送通道。

docs/adr/0005-web-integration-and-performance.md

@@ -0,0 +1,15 @@
+---
+status: accepted
+---
+
+# Web integration and performance
+
+只读接口适配层按领域拆分为 `cockpitApi`、`mapApi`、`detailApi`、`runtimeApi` 等模块。每个模块返回领域对象，不向外暴露后端字段。WebSocket 只作为运行链路，前端消费的也是版本化领域事件；`/ws/deviceStatus` 不作为前端依赖的裸 JSON 字段来源。
+
+地形、倾斜摄影和 3D Tiles 首期按本地或甲方资源接入；天地图仅用于底图校验。管线首期消费后端发布的折线、管径、埋深、材质等属性。Cesium 承担地理渲染，Three.js 只在选中的重点管段或构件上增强。
+
+坐标完全由后端保证；前端只做防御性校验，非法坐标不上图，不尝试自动纠偏。性能目标按 4K 主屏、万级点位以内、20 万级管线段以内设计，分批加载、聚合渲染，真实规模明确后再收紧。首屏优先呈现地图骨架和统计摘要，点位和管线渐进加载，失败分区单独提示。
+
+切换页面、状态刷新或 WebSocket 更新时，保留当前选中对象、面板标签、滚动位置和返回路径；状态更新只修改可变字段，不重建当前视图。
+
+鉴权契约：后端驾驶舱 REST 要求 `Authorization: Bearer <JWT>`，token 只能由 `/login` 签发，而驾驶舱首期不做登录页，因此凭据由部署层注入——生产由网关/反向代理补请求头，开发用同一机制的本地反代或部署配置提供的只读 token。适配层统一附加请求头；页面与 store 不触碰凭据。Cookie 会话不可行（后端 CORS 未开 allowCredentials）。收到的 401 只把受影响分区标为「数据不可用」，保留已成功分区与地图骨架，不跳登录页、不整页遮罩。数据源默认 mock，真实接口由部署配置显式开启，两者走同一适配层。WebSocket 在发送 `cockpitSubscribe` 前先发送 `authenticate` 帧，token 与 REST 同源。

docs/adr/0006-web-code-language-and-structure.md

@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# Web code language and structure
+
+Web 驾驶舱沿用 TvT.js / Fes.js 已有工程约定，不把 TypeScript 增设为项目新规范。新增代码默认使用 JavaScript 和 Vue SFC；只在复用已有 `.ts` 文件或第三方类型声明不可省略时保留局部类型文件，且不扩散为新的项目级规范。可使用少量 JSDoc 帮助编辑器理解，但不引入新的 TypeScript 构建、lint 或目录规范。
+
+驾驶舱自有页面代码继续放在 `src/pages/cockpit/index.vue` 与 `src/modules/cockpit`；开发期可以参考或复用 `src/plugins` 下的现有能力，但最终验收以自有页面为准，不把驾驶舱作为 TvT 插件交付。
+
+`src/pages/cockpit/index.vue` 保持薄，只挂载外壳组件；`CockpitShell` 与全部面板、地图服务、适配层、mock 都收在 `src/modules/cockpit` 这个唯一领域边界内。`src/modules` 是为此新增的顶层目录。不使用 `src/pages/cockpit.vue`，不使用 `layout.vue`，也不在 `.fes.js` 写 `router.routes`（那会让全站文件路由失效）。

docs/adr/0007-web-cockpit-shell-and-plugin-reuse.md

@@ -0,0 +1,9 @@
+---
+status: accepted
+---
+
+# Web cockpit shell and plugin reuse
+
+驾驶舱采用一个 `/cockpit` 页面作为唯一外壳，中央 `MapCanvas` 常驻；一级模式通过 `mode` 状态切换。模式内的全部二级面板同时出现在左右两栏，不再使用 `subview` 状态或二级路由。二级面板只维护 `expandedPanelIds` 展开状态集合；点击标题栏切换展开/收起，切换一级模式时重置为默认展开。
+
+开发期可参考或临时使用 `src/plugins` 下的稳定能力；最终交付以 `src/pages/cockpit/index.vue` 与 `src/modules/cockpit` 为准。`src/pages/cockpit/index.vue` 只挂载 `CockpitShell`，全部业务面板、地图交互、详情流程与适配层都在 `src/modules/cockpit` 内。稳定、通用的插件能力可通过适配层复用；大型插件不作为驾驶舱主体依赖，插件静态资源应复制到驾驶舱自有目录或通过受控服务提供。

docs/adr/0008-web-cockpit-camera-controls.md

@@ -0,0 +1,24 @@
+---
+status: accepted
+---
+
+# Web cockpit camera controls
+
+驾驶舱三维地图使用显式相机控制契约：
+
+- 鼠标左键拖拽：在三维场景中执行摄像机平移；拖拽方向映射为摄像机移动方向，不旋转、不缩放。
+- 鼠标右键拖拽：摄像机围绕“弹簧臂根部/旋转中心”做轨道旋转；旋转过程中不平移、不缩放。
+- 鼠标滚轮：只改变摄像机与旋转中心的距离，即弹簧臂长度；靠近或远离场景目标，不改变中心点，不旋转。
+- Cesium 默认左键旋转、滚轮缩放等行为 SHALL 被替换；相机控制应集中在地图服务层，而不是散落在页面组件中。
+
+旋转中心（弹簧臂根部）的定义：
+
+- 选中监测点或设备时，中心是该对象的**地表高程点**（对象高程 + 0）。
+- 未选中任何对象时，中心是**地面拾取点**（屏幕中心对应的椭球/地形交点）。
+- 右键按下时锁定当时的中心，拖拽过程中不重新拾取。
+- 从无选中到选中时，镜头平滑飞向新中心并保持当前 heading 与 range，只换中心。
+- 取消选中不立即回退中心；左键平移才把中心更新为地面拾取点。
+
+弹簧臂以 `camera.lookAtTransform(中心东北天局部系, HeadingPitchRange)` 表达，因此中心必须是局部地表点，不能是场景或城市原点。
+
+地面/管线视图对相机的影响：管线视图压低弹簧臂、加大 pitch 并把 pitch 下限放宽到允许平视或轻微仰视，同时把管线图层提到可见、把地形与 3D Tiles 压成半透明。切换视图不重置旋转中心，也不新增第二套鼠标绑定。

docs/superpowers/specs/2026-09-09-web-parallel-cockpit.md

@@ -0,0 +1,58 @@
+# Parallel Web Cockpit Spec
+
+## Problem Statement
+
+沅陵县城市生命线驾驶舱目前主要依赖 UE5 交付。需要并行开发一个可替代 UE5 的 Web 驾驶舱，保持既定业务结构、只读边界和后端契约，同时降低部署与国产化适配风险。
+
+## Solution
+
+建立独立 Web 前端驾驶舱工程，复用当前 TvT.js / Fes.js 生态，新增 CesiumJS 作为地理空间主引擎，Three.js 只做局部增强。首期覆盖一张图和总体概览、基础设施、运行监测、预警处置四个只读模式。每个一级模式固定 4 个二级面板同时展示，共 16 个面板；另有 9 个共享详情视图和 5 个预警/报警模式变体。页面采用功能占位 UI，待设计公司资源交付后再替换视觉资产。
+
+## User Stories
+
+1. 作为指挥中心领导，我可以通过一张图查看城市生命线总体态势，以便快速掌握整体风险。
+2. 作为值班人员，我可以在四个业务模式之间切换并保持中央地图不重建，以便持续跟踪空间上下文。
+3. 作为值班人员，我可以在一个一级模式内同时看到全部相关二级面板，以便快速比较信息而不破坏地图状态。
+4. 作为值班人员，我可以点击监测点查看点位摘要和关联设备卡片，以便快速定位问题对象。
+5. 作为值班人员，我可以从设备卡片进入设备详情，以便查看档案、最新指标、预警、报警、工单状态和图片。
+6. 作为值班人员，我可以看到后端解析后的点位状态和原因，以便判断当前风险优先级。
+7. 作为值班人员，我可以在数据过期或分区失败时看到明确状态，以便不误把旧数据当作实时数据。
+8. 作为值班人员，我可以通过 WebSocket 更新和手动刷新获得最新设备状态，以便持续值守。
+9. 作为运维人员，我可以通过部署环境注入凭据和接口地址，以便前端不保存账号或密钥。
+10. 作为验收人员，我可以按契约化 mock 和真实接口两种模式验证页面结构，以便先确认交互再联调数据。
+
+## Implementation Decisions
+
+- 技术栈沿用 TvT.js 生态：Vue 3、Fes.js、TresJS、Three.js、Pinia、UnoCSS、Fes Design / Naive UI；新增 CesiumJS。
+- 驾驶舱入口为 `src/pages/cockpit/index.vue`（薄，只挂载 `CockpitShell`），全部代码收在 `src/modules/cockpit`，不做成 TvT 插件，也不使用 `pluginMaker` 交付。不使用 `layout.vue`，不在 `.fes.js` 写 `router.routes`。
+- 新增代码默认 JavaScript，不把 TypeScript 增设为项目新规范。
+- Cesium 承担底图、地形、3D Tiles、监测点、未关联设备和管线主图；Three.js 只用于重点管线、构件、断面和局部增强。
+- `/cockpit` 是唯一外壳路由；四个一级模式通过 `mode` 内部状态切换。模式内的全部二级面板同时出现在左右两栏，展开状态由 `expandedPanelIds` 维护，中央地图常驻。
+- Pinia 按领域拆分：`mapStore`、`filterStore`、`detailStore`、`runtimeStore`、`uiStore`。
+- API、WebSocket、Cesium、Three.js 均通过服务层访问；页面组件不直接依赖接口字段。
+- 后端契约以现有 `/api/cockpit/v1/...` 控制器、响应结构、演示文档和 `/ws/deviceStatus` 行为为准；当前后端未提供可用 OpenAPI 文档，前端不要求先补 OpenAPI。
+- 契约化 mock 放在 `src/modules/cockpit/mocks`，与真实接口走同一适配层。
+- 静态资产放 `public/cockpit`，不直接依赖 `public/plugins`。
+- Cesium、天地图和后端凭据由部署环境或后端配置注入，前端不硬编码。
+- 非法、缺失、零值、超范围或未校验坐标不上图，但保留在列表和详情中并显示原因。
+- 首期按 4K 主屏、万级点位以内、20 万级管线段以内设计；地图骨架和摘要先显示，点位与管线渐进加载。
+
+## Testing Decisions
+
+- 首期以人工走查为主，验证地图摘要、两级详情、模式切换、状态更新、过期与失败分区。
+- 对坐标校验、状态映射、快照合并、领域适配器等纯逻辑补充少量单测。
+- 不因测试引入新测试框架；不重排现有工程结构。
+
+## Out of Scope
+
+- 管理端写操作、登录、权限管理、工单处置、阈值配置和规则管理。
+- UE5 场景改造、Pixel Streaming 服务端和 Docker 部署。
+- CAD 管线数据转换、坐标精化、GIS 数据生产和高精度模型制作。
+- 竖屏、移动端、超宽屏和多屏拼接。
+- 预警真伪、误报率或准确率判断。
+
+## Further Notes
+
+- 首期验收顺序：地图摘要 → 两级详情 → 14 面板信息结构 → WebSocket/新鲜度 → 3D Tiles/管线增强。
+- 后端接口变更时，先更新适配器和字段字典，不直接改页面结构。
+- 稳定通用插件能力可继续复用，但驾驶舱主体页面和状态流程必须由自有代码承载。