City-Lifeline-Cockpit/docs/adr/0004-web-rendering-and-state-boundaries.md

---

status: accepted

Web rendering and state boundaries

Web 驾驶舱采用“Cesium 为主、Three.js 为增强”的分层方案。Cesium 负责地理坐标下的底图、地形、3D Tiles、全市管线、监测点、未关联设备和空间交互；Three.js 只用于重点管线、接头、阀门、断面、局部构件和面板内可视化，不接管 Cesium 场景。两者通过领域状态和选中对象联动。

本地 TvT.js 案例表明 Three.js 适合自定义材质、Shader、3D Tiles 特写和局部增强；官方 gisPlaneEditor 文档则强调地图底座、影像地形、贴地表达和 GIS 交互。因此全市管线主图交给 Cesium，复杂空间处理不交给 Three.js。

状态管理使用 Pinia，按领域拆分：

• mapStore：地图摘要、分页快照、已加载点位、未关联设备、选中对象、图层可见性。
• filterStore：行业、区域、状态和地面/管线视图。一级模式不属于筛选。地面/管线视图是全局视图条件，同时驱动相机预设与图层可见性（管线视图把地形与 3D Tiles 压成半透明），全局共用且切一级模式不重置。
• detailStore：监测点摘要、设备卡片、设备详情及各分区状态。
• runtimeStore：WebSocket、最后成功刷新时间、手动刷新、过期状态。
• uiStore：当前一级模式 mode、面板展开集合 expandedPanelIds、返回路径、滚动位置、当前标签页。切换一级模式时重置展开集合，不重置行业筛选。

接口和 WebSocket 统一走 service 层；页面组件只消费领域状态，不直接持有接口字段或连接推送通道。