0005-web-integration-and-performance.md 2.6 KB
status: accepted
Web integration and performance
只读接口适配层按领域拆分为 cockpitApi、mapApi、detailApi、runtimeApi 等模块。每个模块返回领域对象，不向外暴露后端字段。WebSocket 只作为运行链路，前端消费的也是版本化领域事件；/ws/deviceStatus 不作为前端依赖的裸 JSON 字段来源。
地形、倾斜摄影和 3D Tiles 首期按本地或甲方资源接入；天地图仅用于底图校验。管线首期消费后端发布的折线、管径、埋深、材质等属性。Cesium 承担地理渲染，Three.js 只在选中的重点管段或构件上增强。
坐标完全由后端保证；前端只做防御性判空、不重算坐标范围，renderable=false 的对象不上图、不尝试自动纠偏（准入判据的唯一来源是后端 coordinateValidation，见 ADR 0002 的 2026-10-12 修订：人工校核前置已取消，改为「结构合法 + 主场景区内」自动准入）。性能目标按 4K 主屏、万级点位以内、20 万级管线段以内设计，分批加载、聚合渲染，真实规模明确后再收紧。首屏优先呈现地图骨架和统计摘要，点位和管线渐进加载，失败分区单独提示。
切换页面、状态刷新或 WebSocket 更新时，保留当前选中对象、面板标签、滚动位置和返回路径；状态更新只修改可变字段，不重建当前视图。一级模式切换的选择态例外见决策地图票 05：三个分项之间互切清空选择；总体概览与任一分项互切保留选择身份，但目标模式不显示该对象时暂停详情与关联监测设备图层，切回且对象仍在当前范围时恢复。一级模式切换只调整可见图层及选择态，不重建一张图，也不因此换地图快照；这项决策的实现属于后续规格，不追认为当前代码行为。
鉴权契约（修订）：驾驶舱只读 REST /api/cockpit/v1/** 与驾驶舱 WebSocket /ws/deviceStatus 不做鉴权；该范围不扩展到后端其他业务路径，也不为未来写接口预留免鉴权规则。默认数据源仍为 mock，真实接口由部署配置显式开启，两者走同一适配层。适配层不在页面和 store 中暴露安全凭据；失败、空态、字段缺失和断线仍按领域分区语义呈现，不回退 mock。原始“REST 注入 Authorization、WS 先 authenticate”决策及其修订记录保留在鉴权决策票。