---
status: accepted
---

# Web integration and performance

只读接口适配层按领域拆分为 `cockpitApi`、`mapApi`、`detailApi`、`runtimeApi` 等模块。每个模块返回领域对象，不向外暴露后端字段。WebSocket 只作为运行链路，前端消费的也是版本化领域事件；`/ws/deviceStatus` 不作为前端依赖的裸 JSON 字段来源。

地形、倾斜摄影和 3D Tiles 首期按本地或甲方资源接入；天地图仅用于底图校验。管线首期消费后端发布的折线、管径、埋深、材质等属性。Cesium 承担地理渲染，Three.js 只在选中的重点管段或构件上增强。

坐标完全由后端保证；前端只做防御性判空、**不重算坐标范围**，`renderable=false` 的对象不上图、不尝试自动纠偏（准入判据的唯一来源是后端 `coordinateValidation`，见 [ADR 0002](0002-web-map-data-and-ui-priority.md) 的 2026-10-12 修订：人工校核前置已取消，改为「结构合法 + 主场景区内」自动准入）。性能目标按 4K 主屏、万级点位以内、20 万级管线段以内设计，分批加载、聚合渲染，真实规模明确后再收紧。首屏优先呈现地图骨架和统计摘要，点位和管线渐进加载，失败分区单独提示。

切换页面、状态刷新或 WebSocket 更新时，保留当前选中对象、面板标签、滚动位置和返回路径；状态更新只修改可变字段，不重建当前视图。**一级模式切换的选择态例外**见[决策地图票 05](../../.scratch/cockpit-point-locate-and-device-link/issues/05-device-point-layer-trigger-and-lifecycle.md)：三个分项之间互切清空选择；总体概览与任一分项互切保留选择身份，但目标模式不显示该对象时暂停详情与关联监测设备图层，切回且对象仍在当前范围时恢复。一级模式切换只调整可见图层及选择态，不重建一张图，也不因此换地图快照；这项决策的实现属于后续规格，不追认为当前代码行为。

鉴权契约（修订）：驾驶舱只读 REST `/api/cockpit/v1/**` 与驾驶舱 WebSocket `/ws/deviceStatus` 不做鉴权；该范围不扩展到后端其他业务路径，也不为未来写接口预留免鉴权规则。默认数据源仍为 mock，真实接口由部署配置显式开启，两者走同一适配层。适配层不在页面和 store 中暴露安全凭据；失败、空态、字段缺失和断线仍按领域分区语义呈现，不回退 mock。原始“REST 注入 Authorization、WS 先 authenticate”决策及其修订记录保留在[鉴权决策票](../../.scratch/web-cockpit-decision-map/issues/07-cockpit-api-auth-without-login.md)。

## 驾驶舱视频操作例外（2026-11-10，需求已决、尚未实施）

来源：[视频监控讨论票117的最终收口摘要](<../../.scratch/cockpit-shell-panel-layout/issues/117-监控设备最新指标增加视频监控入口-需求讨论.md#L55-L107>)。维护者选择视频功能不引入业务账号登录，新增驾驶舱专用视频接口；原管理端页面/接口权限和内部视频服务、ZLM安全边界不变，不为其他业务写操作增加匿名例外。

- 实时视频、已有录像查询/回放、云台及观看会话维护接口免业务账号登录/Authorization；具体新增路径和方法须在视频规格明确，不以全局或旧管理路径的整体放行替代专用接口。
- 匿名不等于取消会话归属、有效性、资源释放、能力与参数校验。API及媒体地址仅限指定可信内网/受限网络，不公网匿名开放；匿名会话不能证明个人实名。
- 使用同一视频通道的其他终端仍可能影响物理云台动作，本期不实现独占互斥、申请控制或控制权租约；保留5秒动作上限、250ms键盘单步、停止兜底与真实验证，不能把发送STOP或媒体会话回收视作设备已安全停止。
- 监控状态刷新/锚点暂隐不重开；关闭、离开设备/模式、选择失效、离页或浏览器页面隐藏释放媒体和停止云台。仅实时视频自动最多五次重连，取消操作终止重连，不自动恢复控制动作；历史/查询手动重试。

上述是明确的视频需求例外，尚未实施，不追认为当前安全规则或现网能力；全部动作仍受本仓构建/debug及启动/下载/设备控制授权边界约束。