# 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/管线增强。
- 后端接口变更时，先更新适配器和字段字典，不直接改页面结构。
- 稳定通用插件能力可继续复用，但驾驶舱主体页面和状态流程必须由自有代码承载。