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

作为指挥中心领导，我可以通过一张图查看城市生命线总体态势，以便快速掌握整体风险。
作为值班人员，我可以在四个业务模式之间切换并保持中央地图不重建，以便持续跟踪空间上下文。
作为值班人员，我可以在一个一级模式内同时看到全部相关二级面板，以便快速比较信息而不破坏地图状态。
作为值班人员，我可以点击监测点查看点位摘要和关联设备卡片，以便快速定位问题对象。
作为值班人员，我可以从设备卡片进入设备详情，以便查看档案、最新指标、预警、报警、工单状态和图片。
作为值班人员，我可以看到后端解析后的点位状态和原因，以便判断当前风险优先级。
作为值班人员，我可以在数据过期或分区失败时看到明确状态，以便不误把旧数据当作实时数据。
作为值班人员，我可以通过 WebSocket 更新和手动刷新获得最新设备状态，以便持续值守。
作为运维人员，我可以通过部署环境注入凭据和接口地址，以便前端不保存账号或密钥。
作为验收人员，我可以按契约化 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/管线增强。
后端接口变更时，先更新适配器和字段字典，不直接改页面结构。
稳定通用插件能力可继续复用，但驾驶舱主体页面和状态流程必须由自有代码承载。

2026-09-09-web-parallel-cockpit.md 4.8 KB Histórico Raw