---
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)。