# Cockpit shell panel layout spec

Status: ready-for-agent

## Problem Statement

Web 驾驶舱此前把 14 个二级视图设计成 `mode/subview` 切换，但这与 UE 原型的实际交互不符。值班人员需要在一个一级模式内同时看到全部相关二级面板，而不是在多个子视图之间来回切换。

## Solution

使用一个 `/cockpit` 外壳承载全部业务模式。中央一张图常驻；用户只切换四个一级模式。进入某个一级模式后，该模式下的全部二级面板同时出现在左右两栏；每个面板通过标题栏展开或收起。

## User Stories

1. 作为指挥中心领导，我希望切换一级模式时中央地图不重建，以便保持空间上下文连续。
2. 作为值班人员，我希望进入一级模式后看到该模式下的全部二级面板，以便快速比较相关信息。
3. 作为值班人员，我希望点击面板标题栏可以收起或展开面板，以便把注意力集中在地图或其他信息上。
4. 作为值班人员，我希望切换一级模式时全部面板恢复默认展开，以便每次进入新场景都有完整上下文。
5. 作为值班人员，我希望左右两栏的面板结构稳定，以便在连续值守时快速定位信息。
6. 作为值班人员，我希望驾驶舱保持只读，以便避免误操作业务状态。
7. 作为设计人员，我希望首期使用功能占位 UI，以便后续只替换视觉资源而不重排信息架构。
8. 作为维护者，我希望驾驶舱代码独立于 TvT 插件目录，以便最终交付边界清晰。
9. 作为测试人员，我希望只通过 `CockpitShell` 这个公共契约验证外壳行为，以便避免陷入内部实现细节。
10. 作为集成人员，我希望接口、WebSocket、Cesium 和 Three.js 都通过服务层访问，以便页面不直接依赖底层实现。
11. 作为值班人员，我希望每个详情分区可以独立成功、失败或过期，以便某一分区异常时仍能看到其他数据。
12. 作为值班人员，我希望无坐标对象不上图但保留在列表中，以便仍能查看业务信息。
13. 作为运维人员，我希望凭据由部署环境注入，以便前端不保存账号或密钥。
14. 作为验收人员，我希望先用契约化 mock 验证外壳行为，再联调真实接口，以便降低联调风险。

## Implementation Decisions

- `/cockpit` 是唯一外壳路由；二级面板不是路由，也不使用 `subview`。
- 一级模式使用 `mode` 状态，包含总体概览、基础设施、运行监测、预警处置。
- 不再使用 `subview` 状态；模式内的二级面板同时展示。
- 面板展开状态使用 `expandedPanelIds` 表示；点击标题栏切换展开/收起。
- 切换一级模式时重置为默认展开。
- `CockpitShell` 是本次唯一公共测试 seam。
- 中央地图通过 `MapCanvas` 常驻，不因模式或面板切换重建。
- 左右两栏的面板数量固定为每个一级模式 4 个：总体概览（态势总览、基础设施、运行监测、预警设置），基础设施（基础档案、运行信息、管理信息、应急保障），运行监测（监测概览、监测分布、运行概况、监测点台账），预警处置（当前预警、历史分析、预警效率、预警分析）。
- 首期代码默认 JavaScript，不引入 TypeScript 作为项目规范。
- 驾驶舱入口为 `src/pages/cockpit/index.vue`（薄，只挂载外壳），全部代码收在 `src/modules/cockpit`。不使用 `src/pages/cockpit.vue`，不使用 `layout.vue`，也不在 `.fes.js` 写 `router.routes`。
- 静态资产位于 `public/cockpit`。
- 接口、WebSocket、Cesium、Three.js 均通过服务层访问。
- 契约化 mock 与真实接口走同一适配层。
- Cesium、天地图和后端凭据由部署环境或后端配置注入，前端不硬编码。

## Testing Decisions

- 通过 `CockpitShell` 验证模式到面板集合的映射。
- 通过 `CockpitShell` 验证面板展开/收起行为。
- 通过 `CockpitShell` 验证切换模式时地图保持常驻。
- 不在本次 spec 中测试单个面板的业务内容。
- 使用人工走查和少量纯逻辑单测；不引入新测试框架。

## Out of Scope

- 管理端写操作、登录、权限管理和工单处置。
- 单个业务面板的详细数据契约和视觉终稿。
- UE5 场景改造、Pixel Streaming、Docker 部署和国产化认证。
- CAD 数据转换、坐标精化和高精度模型制作。
- 竖屏、移动端、超宽屏和多屏拼接。

## Further Notes

- 本 spec 修正了此前 `mode/subview` 的表述。
- ADR 0003 和 0007 已同步更新。