0005-web-integration-and-performance.md 1.9 KB
status: accepted
Web integration and performance
只读接口适配层按领域拆分为 cockpitApi、mapApi、detailApi、runtimeApi 等模块。每个模块返回领域对象，不向外暴露后端字段。WebSocket 只作为运行链路，前端消费的也是版本化领域事件；/ws/deviceStatus 不作为前端依赖的裸 JSON 字段来源。
地形、倾斜摄影和 3D Tiles 首期按本地或甲方资源接入；天地图仅用于底图校验。管线首期消费后端发布的折线、管径、埋深、材质等属性。Cesium 承担地理渲染，Three.js 只在选中的重点管段或构件上增强。
坐标完全由后端保证；前端只做防御性校验，非法坐标不上图，不尝试自动纠偏。性能目标按 4K 主屏、万级点位以内、20 万级管线段以内设计，分批加载、聚合渲染，真实规模明确后再收紧。首屏优先呈现地图骨架和统计摘要，点位和管线渐进加载，失败分区单独提示。
切换页面、状态刷新或 WebSocket 更新时，保留当前选中对象、面板标签、滚动位置和返回路径；状态更新只修改可变字段，不重建当前视图。
鉴权契约：后端驾驶舱 REST 要求 Authorization: Bearer <JWT>，token 只能由 /login 签发，而驾驶舱首期不做登录页，因此凭据由部署层注入——生产由网关/反向代理补请求头，开发用同一机制的本地反代或部署配置提供的只读 token。适配层统一附加请求头；页面与 store 不触碰凭据。Cookie 会话不可行（后端 CORS 未开 allowCredentials）。收到的 401 只把受影响分区标为「数据不可用」，保留已成功分区与地图骨架，不跳登录页、不整页遮罩。数据源默认 mock，真实接口由部署配置显式开启，两者走同一适配层。WebSocket 在发送 cockpitSubscribe 前先发送 authenticate 帧，token 与 REST 同源。