1159 lines
33 KiB
Markdown
1159 lines
33 KiB
Markdown
# 地图模块现状与改造方案
|
||
|
||
## 1. 文档目的
|
||
|
||
本文档用于完整梳理当前地图模块的技术实现、业务能力、数据流转、关键规则、已知问题与性能瓶颈，并给出可分阶段落地的重构方案。目标是：
|
||
|
||
- 让地图模块职责边界清晰，便于后续新增功能；
|
||
- 降低组件、Store、地图引擎之间的耦合；
|
||
- 优化基础图层、锚点、图例、筛选、基地裁切等功能的响应速度；
|
||
- 为后续 2D/3D 扩展、复杂专题图层、更多筛选维度、更多交互能力预留稳定结构。
|
||
|
||
---
|
||
|
||
## 2. 当前模块范围
|
||
|
||
当前地图模块覆盖以下业务能力：
|
||
|
||
- 地图初始化与 2D/3D 切换；
|
||
- GeoServer 基础底图、叠加图层、区域矢量图层加载；
|
||
- Java 后端锚点数据请求、缓存、渲染；
|
||
- 右侧图层树勾选控制图层显示与隐藏；
|
||
- 左侧图例基于图层选中结果动态生成；
|
||
- 图例项点击控制锚点显隐；
|
||
- 基地选择后底图裁切与区域外锚点隐藏；
|
||
- 地图悬停 Popup、点击详情弹窗；
|
||
- 搜索、时间筛选、容量筛选、基地筛选；
|
||
- 某些业务图层的互斥显示与特殊联动；
|
||
- 局部专题菜单下的缩放级别联动动态图层。
|
||
|
||
---
|
||
|
||
## 3. 当前技术实现概览
|
||
|
||
## 3.1 技术栈
|
||
|
||
- 地图引擎：OpenLayers 作为 2D 主引擎，Cesium 作为 3D 引擎入口；
|
||
- 状态管理：Pinia；
|
||
- UI 框架：Vue 3 + `script setup` + Ant Design Vue；
|
||
- 数据来源：
|
||
- GeoServer：基础底图、WMTS、XYZ、GeoJSON 边界；
|
||
- Java 后端接口：图层配置、图例配置、锚点数据；
|
||
- 业务配置：
|
||
- 图层配置与图例配置来自后端；
|
||
- 锚点接口映射规则由 `src/store/modules/GisUrlList.ts` 维护。
|
||
|
||
## 3.2 核心文件职责
|
||
|
||
- `src/components/gis/GisView.vue`
|
||
|
||
- 地图容器入口；
|
||
- 地图初始化；
|
||
- 拉取图层配置与图例配置；
|
||
- 监听菜单切换、基地切换、缩放联动；
|
||
- 挂载 `MapLegend`、`MapFilter`、`MapController`、`BaseLayerSwitcher`。
|
||
|
||
- `src/components/gis/map.class.ts`
|
||
|
||
- 地图能力门面类；
|
||
- 对外屏蔽 OpenLayers / Cesium 差异；
|
||
- 当前主要起到转发作用。
|
||
|
||
- `src/components/gis/map.ol.ts`
|
||
|
||
- OpenLayers 主实现；
|
||
- 负责底图、锚点图层、Popup、图层显隐、区域裁切、量算、定位等；
|
||
- 当前承担了过多业务规则与渲染控制逻辑。
|
||
|
||
- `src/store/modules/map.ts`
|
||
|
||
- 地图图层树、图例、锚点、缓存的核心 Store；
|
||
- 负责图层选中状态、图例选中状态、锚点请求、缓存、图例联动、图层联动；
|
||
- 当前是业务与渲染耦合最重的文件之一。
|
||
|
||
- `src/components/mapController/LayerController.vue`
|
||
|
||
- 图层树 UI；
|
||
- 负责初始基础图层加载；
|
||
- 勾选事件直接调用 Store 更新图层与图例状态；
|
||
- 包含多个互斥业务规则。
|
||
|
||
- `src/components/mapLegend/index.vue`
|
||
|
||
- 图例展示；
|
||
- 基于当前选中图层动态显示；
|
||
- 图例点击后直接驱动地图锚点显隐。
|
||
|
||
- `src/components/mapFilter/index.vue`
|
||
|
||
- 搜索、基地筛选、容量筛选、时间筛选；
|
||
- 直接依赖 `mapStore` 和地图实例；
|
||
- 部分筛选逻辑通过直接修改图例和锚点实现。
|
||
|
||
- `src/components/BaseLayerSwitcher/index.vue`
|
||
|
||
- 底图模式切换器；
|
||
- 切换矢量 / 地形 / 影像底图。
|
||
|
||
- `src/components/gis/gisUtils.ts`
|
||
|
||
- 图层结构拍平；
|
||
- 基础图层 URL 处理；
|
||
- 图例数据转对象；
|
||
- 若干地图布局相关工具。
|
||
|
||
- `src/api/map.ts`
|
||
- 拉取地图配置和图例配置。
|
||
|
||
---
|
||
|
||
## 4. 当前业务能力与逻辑链路
|
||
|
||
## 4.1 初始化流程
|
||
|
||
当前初始化主要发生在 `GisView.vue`：
|
||
|
||
1. 调用 `MapClass.init()` 初始化 OpenLayers；
|
||
2. 调用 `initPopupOverlay()` 挂载悬停 Popup；
|
||
3. 调用 `fetchMapConfigs()` 并行请求：
|
||
- 地图图层配置；
|
||
- 全量图例配置；
|
||
- 当前页面图例配置；
|
||
4. `mapStore.setLegendData()` 初始化图例原始数据与映射；
|
||
5. `mapStore.setLayerData()` 初始化图层树和选中图层 key；
|
||
6. `mapStore.loadAllLayerData()` 递归加载所有有 URL 的图层数据；
|
||
7. `loadLayerData()` 将锚点数据写入缓存并直接调用 `mapClass.addInitDataLayer()` 预创建锚点图层；
|
||
8. 全部锚点加载完成后，再调用 `updateLayerData()` 统一控制初始显示状态；
|
||
9. 图例根据当前选中的图层动态生成并展示。
|
||
|
||
### 现状特点
|
||
|
||
- 当前是“初始化阶段一次性预加载大多数锚点图层，再通过显隐控制”的策略；
|
||
- 图例显示被设计为“锚点完成后再显示”；
|
||
- 地图实例、Store、UI 组件三方互相直接调用。
|
||
|
||
## 4.2 基础图层加载与切换
|
||
|
||
基础底图主要由 `LayerController.vue` 和 `map.ol.ts` 协同完成：
|
||
|
||
- `LayerController.vue` 中监听图层树配置；
|
||
- 对类型为 `GISMap` 的节点解析 `paramJson`，通过 `getMapConfig()` 补齐 GeoServer 地址；
|
||
- 调用 `mapClass.addBaseDataLayer()` 初始化基础图层；
|
||
- 同时调用 `controlBaseLayerTreeShowAndHidden()` 控制显隐；
|
||
- `BaseLayerSwitcher` 再通过 `baseLayerSwitcher()` 在矢量 / 地形 / 影像底图之间切换。
|
||
|
||
当前基础图层类型主要包括：
|
||
|
||
- WMTS：GeoServer WMTS 瓦片；
|
||
- XYZ：例如 DEM 或其他切片图层；
|
||
- vector：部分矢量底图或区域配置。
|
||
|
||
### 自然保护区图层特点
|
||
|
||
- 属于叠加在底图之上的 GIS 图层；
|
||
- 显隐仍通过基础图层控制逻辑处理；
|
||
- 与区域裁切场景存在较强耦合。
|
||
|
||
## 4.3 图层树勾选控制
|
||
|
||
右侧图层树由 `LayerController.vue` 驱动：
|
||
|
||
- 树节点勾选结果通过 `broadcast()` 调用 `mapStore.updateLayerData()`；
|
||
- 图层树中包含多种特殊规则：
|
||
- 视频监控站与 AI 视频监控站互斥；
|
||
- 环保设施和环保设施在建互斥；
|
||
- 珍稀鱼类与沿程鱼类互斥；
|
||
- 初始选中状态通过递归遍历图层树生成。
|
||
|
||
### 现状问题
|
||
|
||
- 互斥逻辑分散在 UI 组件和 Store 两处；
|
||
- “图层树状态”与“地图真实状态”并非单向流；
|
||
- 图层节点既承担展示，又携带业务配置与运行态字段。
|
||
|
||
## 4.4 锚点数据加载
|
||
|
||
锚点数据由 `mapStore.loadAllLayerData()` 和 `loadLayerData()` 负责：
|
||
|
||
- 遍历图层树中全部带 URL 的图层；
|
||
- 使用 `GisUrlList.ts` 将图层 key / title / url 映射成真实请求地址、筛选条件、排序规则；
|
||
- 请求 Java 接口；
|
||
- 将返回记录补充：
|
||
- `iconCode`
|
||
- `code`
|
||
- `_id`
|
||
- `tm`
|
||
- 然后缓存到：
|
||
- `pointDataCache[layerKey]`
|
||
- `layer.data`
|
||
- 合并后的 `pointData`
|
||
- 若地图上还不存在该图层，则直接调用 `mapClass.addInitDataLayer()` 创建 `VectorLayer`。
|
||
|
||
### 当前锚点渲染方式
|
||
|
||
- 每个 `pointMap` 图层对应一个 `VectorLayer`；
|
||
- 每个点被转为 `Feature<Point>`；
|
||
- Feature 上维护多个运行态字段：
|
||
- `_iconUrl`
|
||
- `_labelText`
|
||
- `_legendVisible`
|
||
- `_regionVisible`
|
||
- `_layerKey`
|
||
- 样式函数 `createPointStyle()` 在渲染时综合判断：
|
||
- 图例是否显示；
|
||
- 是否在基地区域内；
|
||
- 当前缩放级别；
|
||
- 点之间距离阈值；
|
||
- 是否悬停。
|
||
|
||
## 4.5 图例动态生成与点击联动
|
||
|
||
图例数据来源于两部分：
|
||
|
||
- `legendDataOriginal`：后端返回的全量图例；
|
||
- `legendDataSelected`：根据当前选中的图层动态筛选后的图例结构。
|
||
|
||
当前机制：
|
||
|
||
1. 初始化时拉取全部图例；
|
||
2. 通过 `layerCode` 与图层树选中结果建立关联；
|
||
3. `mapStore.updateLayerData()` 重新计算当前选中的图例树；
|
||
4. `MapLegend` 监听 `legendDataSelected` 进行展示；
|
||
5. 点击图例项后：
|
||
- 更新 Store 中图例 checked 状态；
|
||
- 若是锚点图层，则调用 `mapClass.setLegendPointVisible()`；
|
||
- 若是 GIS 图层，则调用 `controlBaseLayerTreeShowAndHidden()`。
|
||
|
||
### 环保设施特殊逻辑
|
||
|
||
- 勾选 `fp_point`、`eq_point`、`fb_point`、`vp_point`、`va_point`、`sg_point`、`dw_point` 中任意图层时，图例自动补充“环保设施”分组；
|
||
- 全部取消时自动移除该图例分组。
|
||
|
||
## 4.6 筛选与搜索
|
||
|
||
`MapFilter` 负责以下功能：
|
||
|
||
- 装机容量筛选；
|
||
- 锚点关键字搜索；
|
||
- 时间筛选；
|
||
- 基地筛选；
|
||
- 个别专题下的鱼类分布筛选。
|
||
|
||
当前实现方式：
|
||
|
||
- 搜索下拉列表从 `pointData` 里计算；
|
||
- 只展示当前已选中图层中的锚点；
|
||
- 容量筛选直接修改图例状态，并调用 `map.mdLayerShowOrHidden()` 控制 feature 显隐；
|
||
- 时间筛选通过 `mapStore.updateSearchTimeRange()` 清缓存、删图层、重新请求；
|
||
- 基地切换通过监听 `JidiSelectEventStore.selectedItem` 联动地图区域裁切。
|
||
|
||
## 4.7 基地选择与区域裁切
|
||
|
||
基地逻辑入口在 `GisView.vue` 监听器中：
|
||
|
||
- 当基地变化时，调用 `mapClass.jdPanelControlShowAndHidden()`；
|
||
- `map.ol.ts` 内会：
|
||
- 更新当前 `BASEID`；
|
||
- 请求基地 GeoJSON 边界；
|
||
- 隐藏所有锚点；
|
||
- 通过射线法判断锚点是否在区域内；
|
||
- 标记 `_regionVisible`；
|
||
- 调整视角；
|
||
- 对底图应用遮罩。
|
||
|
||
### 该能力的业务效果
|
||
|
||
- 只显示当前基地区域内的锚点；
|
||
- 底图裁切到当前基地范围；
|
||
- 全选时取消遮罩并显示全部锚点。
|
||
|
||
## 4.8 Popup 与点击详情
|
||
|
||
当前交互如下：
|
||
|
||
- `pointermove` 时调用 `detectFeatureAtPixel()` 检查命中点要素；
|
||
- 若命中图标区域，则：
|
||
- 更新鼠标指针；
|
||
- 更新 `hoveredFeatureId`；
|
||
- 调用 `showPopup()` 展示悬停浮窗；
|
||
- 重绘所有点图层；
|
||
- `click` 命中点要素时，打开详情弹窗并将 feature 属性写入 `modelStore`。
|
||
|
||
### 当前特点
|
||
|
||
- Popup 内容由 `popupHtml` 或 `generatePopupHtml(props)` 生成；
|
||
- 命中检测采用逐像素回调加距离二次判断；
|
||
- 所有点图层在 hover 状态切换时都会 `layer.changed()`。
|
||
|
||
## 4.9 菜单与缩放级别联动
|
||
|
||
在水电开发状况菜单下：
|
||
|
||
- 地图缩放级别大于等于 12 时自动添加一组动态图层；
|
||
- 缩回 12 以下时自动移除；
|
||
- 菜单切换时会根据当前层级重新判断是否添加。
|
||
|
||
当前动态图层 key 包括：
|
||
|
||
- `dw_point`
|
||
- `stinfo_video_point`
|
||
- `stinfo_gjllz_point`
|
||
- `wt_point`
|
||
- `wq_ownWq_point`
|
||
- `wq_countryWq_point`
|
||
- `fp_point`
|
||
- `eq_point`
|
||
- `fb_point`
|
||
- `vp_point`
|
||
- `va_point`
|
||
- `sg_point`
|
||
|
||
---
|
||
|
||
## 5. 当前数据流与调用关系
|
||
|
||
当前主数据流可概括为：
|
||
|
||
1. `GisView.vue` 拉取配置；
|
||
2. `mapStore` 保存图层树、图例、缓存；
|
||
3. `LayerController.vue` / `MapLegend.vue` / `MapFilter.vue` 直接操作 `mapStore`；
|
||
4. `mapStore` 又直接调用 `mapClass`；
|
||
5. `mapClass` 继续转发到 `map.ol.ts`；
|
||
6. `map.ol.ts` 内部维护图层注册表和 Feature 运行态；
|
||
7. 地图状态变化后，组件又通过监听 Store 再次更新 UI。
|
||
|
||
### 现有结构本质
|
||
|
||
当前是“多入口、多方向写状态”的结构：
|
||
|
||
- 组件可以改 Store；
|
||
- 组件可以直接调地图；
|
||
- Store 可以直接调地图；
|
||
- 地图内部又维护一套运行态；
|
||
- 图例、图层树、地图显隐存在多份状态镜像。
|
||
|
||
这会导致：
|
||
|
||
- 状态同步成本高；
|
||
- 某些场景下容易出现 UI 勾选状态与实际地图状态不一致；
|
||
- 新增规则时只能继续在现有逻辑上叠加 `if/else`。
|
||
|
||
---
|
||
|
||
## 6. 当前存在的主要问题
|
||
|
||
## 6.1 架构层面问题
|
||
|
||
### 1. UI、业务编排、地图渲染耦合过深
|
||
|
||
- `LayerController.vue`、`MapLegend.vue`、`MapFilter.vue` 都直接调 Store 和地图实例；
|
||
- `map.ts` 同时负责：
|
||
- 请求；
|
||
- 缓存；
|
||
- 图例结构整理；
|
||
- 图层勾选；
|
||
- 地图显隐；
|
||
- 业务互斥；
|
||
- `map.ol.ts` 同时负责：
|
||
- OpenLayers 适配；
|
||
- 业务过滤；
|
||
- 区域裁切；
|
||
- 弹窗；
|
||
- 图例控制；
|
||
- 锚点显示策略。
|
||
|
||
### 2. 缺乏清晰的单向数据流
|
||
|
||
- 图层树 checked、图例 checked、Feature `_legendVisible`、Layer visible 都是状态源；
|
||
- 任何一个点修改后都可能触发联动，难以推断最终状态；
|
||
- 某些流程依赖顺序正确才能表现正常。
|
||
|
||
### 3. 业务规则分散
|
||
|
||
- 互斥规则分散在 `LayerController.vue` 和 `map.ts`；
|
||
- 环保设施图例补充逻辑在 `map.ts`；
|
||
- 装机容量筛选逻辑在 `MapFilter.vue`；
|
||
- 基地区域过滤逻辑在 `map.ol.ts`；
|
||
- 这些规则没有统一归口，新增业务会继续扩大分散度。
|
||
|
||
## 6.2 性能问题
|
||
|
||
### 1. 初始化阶段预加载过重
|
||
|
||
- `loadAllLayerData()` 会递归处理大量图层；
|
||
- 即使图层未勾选，也会提前请求并建图层；
|
||
- 页面首次进入时网络压力和首屏渲染压力较大。
|
||
|
||
### 2. 递归遍历频繁
|
||
|
||
- 图层树查找 `findLayerByKey()` 多次递归；
|
||
- 图例生成 `getlegendData()` 递归；
|
||
- `updateLayerData()` 每次变化都要递归更新 checked 状态；
|
||
- 搜索项计算 `anchorPointOptions` 也会递归收集图层 key。
|
||
|
||
### 3. 锚点显隐是全量 feature 遍历
|
||
|
||
- 图例点击时逐个遍历 feature；
|
||
- 基地裁切时逐个 feature 做点在面内判断；
|
||
- hover 时所有点图层重绘；
|
||
- 缩放变化会重复执行样式计算。
|
||
|
||
### 4. 底图切换会 remove / add 图层
|
||
|
||
- `baseLayerSwitcher()` 每次切换都移除旧底图再新增；
|
||
- 对 WMTS / XYZ 来说会造成重复创建图层对象和重复请求开销。
|
||
|
||
## 6.3 一致性与可靠性问题
|
||
|
||
### 1. 存在明显临时代码与未收敛逻辑
|
||
|
||
- `GisView.vue` 中 `fetchMapConfigs()` 里对图层做了 `splice(0, 2)` 临时截断；
|
||
- 日志仍显示“临时限制”，说明线上逻辑可能仍处于测试状态。
|
||
|
||
### 2. 存在未定义引用
|
||
|
||
- `GisView.vue` 切换地图后调用 `fetchPointData()`，但项目中未找到定义；
|
||
- `map.ts` 中使用了 `wq_lineTime`、`wt_lineTime`，但项目中未找到定义。
|
||
|
||
### 3. 请求去重逻辑未真正落地
|
||
|
||
- `map.ts` 中生成了 `requestIdentifier`，但未实际用于请求去重；
|
||
- `requestParamsCopy` 也未参与有效逻辑。
|
||
|
||
### 4. 图层状态与渲染状态容易失同步
|
||
|
||
- `layer.checked`、`checkedLayerKeys`、图例 checked、Feature 可见状态是多份数据；
|
||
- 其中任意一份被跳过更新，就可能出现视觉不一致。
|
||
|
||
### 5. 部分代码存在明显遗留痕迹
|
||
|
||
- `addInitDataLayer()` 中存在无意义语句 `3;`；
|
||
- 有重复日志；
|
||
- 有注释掉的大量旧逻辑；
|
||
- 说明代码迁移过程中缺乏结构性收口。
|
||
|
||
## 6.4 可维护性问题
|
||
|
||
### 1. Store 过大
|
||
|
||
- `map.ts` 既是数据仓库，又是调度器，又是业务规则中心；
|
||
- 后续新增图层类型、筛选类型、专题逻辑时，文件会持续膨胀。
|
||
|
||
### 2. MapOl 职责过多
|
||
|
||
- 当前 `map.ol.ts` 既是 OpenLayers 适配器，又是图层经理、锚点经理、Popup 经理、区域裁切经理；
|
||
- 单文件理解和修改成本已经偏高。
|
||
|
||
### 3. 缺少规范化类型系统
|
||
|
||
- 大量 `any`；
|
||
- 图层配置、图例配置、锚点数据、请求映射结构都没有稳定类型；
|
||
- 特殊图层规则依赖字符串常量散落在各处。
|
||
|
||
---
|
||
|
||
## 7. 改造目标
|
||
|
||
本次改造建议达成以下目标：
|
||
|
||
### 7.1 结构目标
|
||
|
||
- 建立清晰的四层结构：视图层、应用编排层、领域状态层、地图渲染层；
|
||
- 收拢业务规则，不再散落到多个 UI 组件和地图引擎实现中；
|
||
- 建立稳定的数据模型与类型定义。
|
||
|
||
### 7.2 性能目标
|
||
|
||
- 首屏只加载必要图层；
|
||
- 选中图层优先加载，未选中图层延后或懒加载；（待考虑）
|
||
- 图例切换、基地切换、搜索筛选尽量使用索引和差量更新；
|
||
- 减少重复递归、重复建图层、重复样式重算。
|
||
|
||
### 7.3 维护目标
|
||
|
||
- 新增图层类型、专题规则、图例规则时有固定扩展点；
|
||
- 2D/3D 共享统一业务层，底层只替换渲染适配器；
|
||
- 可以较容易增加埋点、日志、调试工具和单元测试。
|
||
|
||
---
|
||
|
||
## 8. 目标架构设计
|
||
|
||
建议将地图模块拆分为四层：
|
||
|
||
## 8.1 视图层
|
||
|
||
只负责展示和用户交互，不直接编写复杂业务逻辑。
|
||
|
||
建议保留的组件：
|
||
|
||
- `GisView.vue`
|
||
- `LayerController.vue`
|
||
- `MapLegend.vue`
|
||
- `MapFilter.vue`
|
||
- `BaseLayerSwitcher.vue`
|
||
|
||
视图层职责：
|
||
|
||
- 展示树、图例、筛选项、底图切换器；
|
||
- 分发用户动作；
|
||
- 订阅 Store 派生结果；
|
||
- 不直接调用 `map.ol.ts` 里的业务方法。
|
||
|
||
## 8.2 应用编排层
|
||
|
||
新增地图编排层，建议命名为：
|
||
|
||
- `src/modules/map/application/map-orchestrator.ts`
|
||
- 或 `src/components/gis/core/orchestrator.ts`
|
||
|
||
职责：
|
||
|
||
- 承接 UI 动作；
|
||
- 统一处理“图层勾选、图例勾选、基地切换、时间筛选、搜索定位、底图切换”等命令；
|
||
- 控制加载顺序；
|
||
- 根据状态差异驱动地图渲染层；
|
||
- 管理互斥规则和特殊规则。
|
||
|
||
### 推荐模式
|
||
|
||
所有 UI 动作统一转换成 Command：
|
||
|
||
- `toggleLayer(layerKey)`
|
||
- `toggleLegend(layerKey, legendKey)`
|
||
- `switchBaseMap(baseMapKey)`
|
||
- `changeBaseRegion(baseId)`
|
||
- `changeTimeRange(range)`
|
||
- `focusPoint(pointId)`
|
||
|
||
## 8.3 领域状态层
|
||
|
||
保留 Pinia，但将当前大 Store 拆分为多个职责明确的 Store / Service：
|
||
|
||
- `mapConfigStore`
|
||
|
||
- 保存图层树、图例原始配置、页面配置；
|
||
|
||
- `mapViewStateStore`
|
||
|
||
- 保存当前选中图层、选中图例、当前底图、当前基地、当前时间范围、当前缩放级别；
|
||
|
||
- `mapDataStore`
|
||
|
||
- 保存锚点缓存、请求状态、加载状态、错误状态；
|
||
|
||
- `mapRuleEngine`
|
||
- 保存互斥规则、派生规则、特殊专题规则。
|
||
|
||
## 8.4 地图渲染层
|
||
|
||
保留 `MapClass` 作为统一门面，但将 `MapOl` 拆分成多个 Manager：
|
||
|
||
- `ol-map-adapter.ts`
|
||
|
||
- 只负责地图实例生命周期；
|
||
|
||
- `ol-base-layer-manager.ts`
|
||
|
||
- 负责 WMTS / XYZ / GeoJSON / 底图切换；
|
||
|
||
- `ol-point-layer-manager.ts`
|
||
|
||
- 负责锚点图层创建、更新、索引、显隐；
|
||
|
||
- `ol-popup-manager.ts`
|
||
|
||
- 负责 hover / click / popup；
|
||
|
||
- `ol-region-mask-manager.ts`
|
||
|
||
- 负责基地裁切、遮罩、点在面内过滤；
|
||
|
||
- `ol-interaction-manager.ts`
|
||
- 负责缩放监听、量算、定位等。
|
||
|
||
这样做后，`MapOl` 只保留聚合职责，不再直接承载全部细节。
|
||
|
||
---
|
||
|
||
## 9. 详细改造方案
|
||
|
||
## 9.1 统一领域模型
|
||
|
||
首先建立类型定义，避免继续依赖 `any`。
|
||
|
||
建议新增：
|
||
|
||
- `types/map-layer.ts`
|
||
- `types/map-legend.ts`
|
||
- `types/map-point.ts`
|
||
- `types/map-rule.ts`
|
||
|
||
### 图层类型建议
|
||
|
||
- `BaseMapLayer`
|
||
- `OverlayLayer`
|
||
- `PointLayer`
|
||
- `RegionMaskLayer`
|
||
- `DynamicLayer`
|
||
|
||
### 图层运行态建议(待考虑)
|
||
|
||
将运行态从后端配置中剥离，不再直接把运行态写回原始配置：
|
||
|
||
- `config`: 后端返回配置，只读；
|
||
- `runtime`:
|
||
- `visible`
|
||
- `loaded`
|
||
- `loading`
|
||
- `error`
|
||
- `featureCount`
|
||
- `lastRequestKey`
|
||
- `lastUpdatedAt`
|
||
|
||
## 9.2 统一图层树、图例、地图显隐状态源
|
||
|
||
建议明确一个唯一状态源：
|
||
|
||
- 图层是否勾选：只认 `selectedLayerKeys`；
|
||
- 图例是否勾选：只认 `selectedLegendKeys`；
|
||
- 地图渲染层不再存业务真相，只接收派生后的可见性差量。
|
||
|
||
### 派生关系建议
|
||
|
||
- `selectedLayerKeys` -> 派生当前显示的图例组；
|
||
- `selectedLayerKeys + selectedLegendKeys + currentBaseId` -> 派生 Feature 可见性；
|
||
- `selectedBaseMapKey` -> 派生当前底图组合；
|
||
- `timeRange + filterConditions` -> 派生图层请求签名。
|
||
|
||
## 9.3 建立图层索引与图例索引
|
||
|
||
为提升速度，初始化配置后立即建立索引：
|
||
|
||
- `layerByKey`
|
||
- `legendByNameEn`
|
||
- `legendByLayerCode`
|
||
- `childrenByParentKey`
|
||
- `layerDescendantsByKey`
|
||
- `featureIndexByLayerAndLegendKey`
|
||
|
||
### 优化收益
|
||
|
||
- 避免每次 `findLayerByKey()` 递归；
|
||
- 图例切换时直接定位对应图层和对应 feature 集合；
|
||
- 图层树勾选联动时只处理差异节点。
|
||
|
||
## 9.4 抽离请求解析器
|
||
|
||
当前 `GisUrlList.ts` 的匹配逻辑散落在 `loadLayerData()` 中，建议拆出：
|
||
|
||
- `map-layer-request-resolver.ts`
|
||
|
||
职责：
|
||
|
||
- 根据 `layer.key` / `layer.title` / `layer.url` 解析真实请求；
|
||
- 生成标准请求结构：
|
||
- `url`
|
||
- `method`
|
||
- `filter`
|
||
- `sort`
|
||
- `cacheKey`
|
||
|
||
### 进一步建议
|
||
|
||
- 在应用启动时将 `GisUrlList.ts` 预编译成多索引字典；
|
||
- 不要在每次 `loadLayerData()` 内重新构建 `urlListDict`；
|
||
- 请求签名应真正参与去重和缓存。
|
||
|
||
## 9.5 重新设计锚点加载策略(待考虑)
|
||
|
||
建议从“全量预加载”改为“分层加载”：
|
||
|
||
### 第一阶段
|
||
|
||
- 首屏只加载默认勾选图层；
|
||
- 图例也只基于已加载的默认勾选图层生成；
|
||
|
||
### 第二阶段(待考虑)
|
||
|
||
- 对常用图层做后台低优先级预取；
|
||
- 非常规图层在首次勾选时再加载；
|
||
|
||
### 第三阶段(待考虑)
|
||
|
||
- 对时间敏感或高频筛选图层使用缓存失效策略：
|
||
- `cacheKey = layerKey + requestSignature`
|
||
- 基于时间范围、基地、专题条件生成。
|
||
|
||
### 配套措施(待考虑)
|
||
|
||
- 增加并发控制，例如同时最多 4 到 6 个接口请求；
|
||
- 增加可取消请求，避免菜单切换时旧请求回写新页面；
|
||
- 记录每个图层单独 loading 和 error 状态。
|
||
|
||
## 9.6 重构点图层渲染管理
|
||
|
||
建议将点图层改造成“图层级管理 + 索引级更新”模式。
|
||
|
||
### 当前问题
|
||
|
||
- 图例点击靠遍历全量 feature；
|
||
- 基地裁切靠遍历全量 feature；
|
||
- hover 时所有点图层都重绘。
|
||
|
||
### 改造建议
|
||
|
||
在 `PointLayerManager` 中维护以下索引：
|
||
|
||
- `featuresByLayerKey`
|
||
- `featuresByLegendKey`
|
||
- `featuresByBaseId`
|
||
- `featureById`
|
||
|
||
### 改造后的显隐策略
|
||
|
||
- 图例点击时，只处理该图例对应 feature 集合；
|
||
- 基地切换时，优先按 `baseId` 做粗筛，再对边界交叉区域做点在面内判断；
|
||
- 图层勾选时只切换对应 `VectorLayer.visible`；
|
||
- 非必要不重新 `addFeatures()`。
|
||
|
||
### 样式策略建议
|
||
|
||
- 保留 style function，但减少在 style function 内做复杂业务判断；
|
||
- 将 `_legendVisible`、`_regionVisible`、`_layerVisible` 预先计算为单个 `renderVisible` 标记；
|
||
- 样式函数只做：
|
||
- 是否可见；
|
||
- 当前缩放级别；
|
||
- 当前 hover 状态；
|
||
- 图标与文本样式计算。
|
||
|
||
## 9.7 底图与叠加层管理重构(待考虑)
|
||
|
||
建议明确区分三类图层：
|
||
|
||
- 主底图：矢量 / 地形 / 影像三选一；
|
||
- 基础叠加层：自然保护区、行政边界等可附加；
|
||
- 专题锚点层：水电工程、生态流量、水质站、视频站等。
|
||
|
||
### 当前问题
|
||
|
||
- 底图切换会 remove / add `customBaseLayer`；
|
||
- 主底图和叠加底图概念混杂；
|
||
- `controlBaseLayerTreeShowAndHidden()` 实际控制的不全是底图。
|
||
|
||
### 改造建议
|
||
|
||
- 维护 `currentBaseMapKey`；
|
||
- 主底图预创建，切换时只改 visible；
|
||
- 叠加层作为独立 overlay 管理；
|
||
- 自然保护区等图层明确归类为 overlay，不与主底图复用同一逻辑。
|
||
|
||
## 9.8 图例模块重构
|
||
|
||
建议把“图例结构”和“图例选中态”彻底分离：
|
||
|
||
- `legendSchema`: 后端原始图例树；
|
||
- `legendVisibleTree`: 根据当前图层选择派生；
|
||
- `legendCheckedSet`: 当前选中的图例 key 集。
|
||
|
||
### 这样做的好处
|
||
|
||
- 后端原始图例树不再被运行态污染；
|
||
- 图例点击只更新 `legendCheckedSet`；
|
||
- 图层变化只重算当前显示哪些图例，不直接修改原始结构；
|
||
- 更容易实现“重置图例”、“记忆用户图例偏好”。
|
||
|
||
## 9.9 基地裁切与区域过滤重构
|
||
|
||
建议将基地逻辑完全收口到 `RegionMaskManager`。
|
||
|
||
### 改造重点
|
||
|
||
- 缓存基地 GeoJSON；
|
||
- 一次解析边界，多次复用；
|
||
- 对点位先按 `baseId` 粗筛，再按 polygon 精筛；
|
||
- 避免每次基地切换都重新请求已缓存边界；
|
||
- 底图遮罩和锚点区域过滤使用同一份区域上下文。
|
||
|
||
### 进一步优化
|
||
|
||
- 若后端能返回基地与锚点的归属关系，可优先直接按 `baseId` 过滤；
|
||
- 点在面内判断只作为兜底校验；
|
||
- 对非常大的多边形可预处理 bbox，先做 bbox 命中，再做射线法。 -
|
||
- 有一个 baseID 来传值 直接请求接口数据加载
|
||
- const url = this.hydropBaseConfig.geojson_url + `&cql_filter=BASEID='${this.BASEID}'`; console.log('正在请求裁切数据:', url);
|
||
|
||
// 等待数据加载
|
||
const geoJsonData = await this.loadGeoJsonData(url);
|
||
|
||
## 9.10 Popup 与交互重构
|
||
|
||
建议将 Popup 逻辑从 `MapOl` 中抽离：
|
||
|
||
- `PopupManager` 负责：
|
||
- hover 命中检测；
|
||
- popup 位置；
|
||
- popup 内容渲染；
|
||
- click 详情回调；
|
||
|
||
### 优化方向
|
||
|
||
- 命中检测尽量只针对当前可见的点图层；
|
||
- 对 hover 更新增加最小移动阈值；
|
||
- 只重绘当前命中 feature 所在图层，而不是所有点图层；
|
||
- Popup 内容生成应支持模板注册，不直接在地图层拼接业务 HTML。
|
||
|
||
## 9.11 业务规则引擎化
|
||
|
||
建议把分散的特殊规则抽到统一规则层。
|
||
|
||
### 当前应纳入规则引擎的规则
|
||
|
||
- 视频监控站与 AI 视频监控站互斥；
|
||
- 环保设施与环保设施在建互斥；
|
||
- 珍稀鱼类与沿程鱼类互斥；
|
||
- 环保设施图例自动补充；
|
||
- 水电开发状况菜单的缩放级别动态图层；
|
||
- 水质断面多接口拼接；
|
||
- 生态流量三级数据结构处理。
|
||
|
||
### 建议实现方式
|
||
|
||
定义规则接口：
|
||
|
||
```ts
|
||
interface MapBusinessRule {
|
||
id: string;
|
||
when(context: RuleContext): boolean;
|
||
apply(context: RuleContext): RulePatch;
|
||
}
|
||
```
|
||
|
||
这样新增业务时只加规则文件，不再继续往组件和 Store 塞判断。
|
||
|
||
## 9.12 组件层改造建议
|
||
|
||
### `GisView.vue`
|
||
|
||
- 只保留地图容器、初始化、模块挂载；
|
||
- 配置请求交给 `mapOrchestrator.initialize(pageKey)`；
|
||
- 菜单切换、基地切换也只发送命令。
|
||
|
||
### `LayerController.vue`
|
||
|
||
- 只处理树控件展示与事件抛出；
|
||
- 互斥逻辑不要写在组件中；
|
||
- 初始底图加载不要放在组件 watch 里，改到编排层统一处理。
|
||
|
||
### `MapLegend.vue`
|
||
|
||
- 只负责展示图例树和发出切换事件；
|
||
- 不直接调用 `mapClass`。
|
||
|
||
### `MapFilter.vue`
|
||
|
||
- 搜索、容量、时间、基地变化全部改为发送标准命令；
|
||
- 过滤后的锚点候选列表由 Store 派生，不在组件里自行拼装业务逻辑。
|
||
|
||
### `BaseLayerSwitcher.vue`
|
||
|
||
- 只负责切换主底图；
|
||
- 不关心图层树中 `customBaseLayer` 的内部结构。
|
||
|
||
## 9.13 日志、监控与调试能力(待考虑)
|
||
|
||
建议补充以下调试能力：
|
||
|
||
- 图层加载耗时；
|
||
- 单图层接口耗时；
|
||
- 首屏加载耗时；
|
||
- 当前可见图层列表；
|
||
- 当前可见锚点数量；
|
||
- 当前选中图例数量；
|
||
- 当前缓存命中率；
|
||
- 当前基地裁切耗时。
|
||
|
||
可以在开发模式下提供一个简易的地图调试面板，便于排查性能与状态同步问题。
|
||
|
||
---
|
||
|
||
## 10. 分阶段落地方案
|
||
|
||
建议采用“四阶段渐进式改造”，避免一次性大改导致风险过高。
|
||
|
||
## 第 1 阶段：收口现状与止血
|
||
|
||
目标：不改变功能表现，先把明显风险收口。
|
||
|
||
建议内容：
|
||
|
||
- 去掉测试遗留逻辑，如 `splice(0, 2)`；
|
||
- 修复未定义方法和未定义变量；
|
||
- 清理重复日志、无效代码、注释垃圾；
|
||
- 补充类型定义；
|
||
- 建立 `layerByKey`、`legendByNameEn` 等基础索引；
|
||
- 将互斥规则从组件内搬到 Store 或规则层统一处理；
|
||
- 实现真实请求去重和请求取消。
|
||
|
||
## 第 2 阶段：拆 Store 与编排层
|
||
|
||
目标：建立单向数据流。
|
||
|
||
建议内容：
|
||
|
||
- 新增 `mapOrchestrator`；
|
||
- 拆 `map.ts` 为配置、状态、数据三个模块；
|
||
- UI 组件只发送命令；
|
||
- 图例派生、图层派生、筛选派生全部收口到编排层。
|
||
|
||
## 第 3 阶段：拆地图渲染层
|
||
|
||
目标：把 `MapOl` 大文件拆开。
|
||
|
||
建议内容：
|
||
|
||
- 抽 `BaseLayerManager`；
|
||
- 抽 `PointLayerManager`；
|
||
- 抽 `PopupManager`；
|
||
- 抽 `RegionMaskManager`；
|
||
- 明确地图引擎层只负责“渲染执行”，不处理业务真相。
|
||
|
||
## 第 4 阶段：性能强化与能力扩展
|
||
|
||
目标：让模块适合长期迭代。
|
||
|
||
建议内容：
|
||
|
||
- 实现懒加载与后台预取；
|
||
- feature 索引化；
|
||
- 地图交互性能优化；
|
||
- 支持规则插件化；
|
||
- 补充测试与性能指标看板；
|
||
- 为 3D 共用业务层做适配。
|
||
|
||
---
|
||
|
||
## 11. 推荐目录结构
|
||
|
||
建议重构后目录大致如下：
|
||
|
||
```text
|
||
src/
|
||
modules/
|
||
map/
|
||
application/
|
||
map-orchestrator.ts
|
||
map-commands.ts
|
||
map-rule-engine.ts
|
||
domain/
|
||
types/
|
||
map-layer.ts
|
||
map-legend.ts
|
||
map-point.ts
|
||
map-filter.ts
|
||
services/
|
||
layer-request-resolver.ts
|
||
legend-deriver.ts
|
||
layer-deriver.ts
|
||
infrastructure/
|
||
stores/
|
||
map-config.store.ts
|
||
map-view-state.store.ts
|
||
map-data.store.ts
|
||
repositories/
|
||
map-config.repository.ts
|
||
map-point.repository.ts
|
||
render/
|
||
map.class.ts
|
||
ol/
|
||
ol-map-adapter.ts
|
||
ol-base-layer-manager.ts
|
||
ol-point-layer-manager.ts
|
||
ol-popup-manager.ts
|
||
ol-region-mask-manager.ts
|
||
ol-interaction-manager.ts
|
||
components/
|
||
gis/
|
||
GisView.vue
|
||
mapController/
|
||
LayerController.vue
|
||
mapLegend/
|
||
index.vue
|
||
mapFilter/
|
||
index.vue
|
||
BaseLayerSwitcher/
|
||
index.vue
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 重点业务的改造策略
|
||
|
||
## 12.1 基础图层
|
||
|
||
策略：
|
||
|
||
- 单独定义主底图与叠加图层；
|
||
- 预创建主底图；
|
||
- 切换时仅改 visible；
|
||
- `customBaseLayer` 不再作为特殊魔法 key 到处透传。
|
||
|
||
## 12.2 水电工程锚点
|
||
|
||
策略：
|
||
|
||
- 作为标准 `PointLayer` 处理；
|
||
- 保留当前图标、标签、距离阈值、Popup 规则；
|
||
- 在 `PointLayerManager` 中建立 feature 索引。
|
||
|
||
## 12.3 生态流量三级数据
|
||
|
||
策略：
|
||
|
||
- 在领域层定义树结构转换器；
|
||
- Store 不直接关心层级深浅；
|
||
- 图层树组件只拿已经标准化后的树。
|
||
|
||
## 12.4 水质监测断面三接口拼接
|
||
|
||
策略：
|
||
|
||
- 不在 UI 或 Store 中散写拼接逻辑；
|
||
- 建立专题数据聚合器，例如 `water-quality-point-aggregator.ts`；
|
||
- 对外输出统一的 `PointLayerData`。
|
||
|
||
## 12.5 视频监控站与 AI 视频监控站互斥
|
||
|
||
策略：
|
||
|
||
- 写成标准业务规则；
|
||
- 由规则引擎统一裁剪勾选结果；
|
||
- UI 不再内嵌业务互斥判断。
|
||
|
||
## 12.6 自然保护区与区域底图
|
||
|
||
策略：
|
||
|
||
- 统一归类为 `OverlayLayer`；
|
||
- 与主底图切换分离；
|
||
- 与基地裁切共享区域上下文。
|
||
|
||
---
|
||
|
||
## 13. 测试与验收建议
|
||
|
||
## 13.1 功能验收清单
|
||
|
||
- 页面首次进入，默认勾选图层正确显示；
|
||
- 图层树勾选与取消勾选，地图表现与图例表现一致；
|
||
- 图例点击后，仅影响对应锚点；
|
||
- 基地切换后，区域外锚点正确隐藏；
|
||
- 底图切换不影响锚点和图例状态；
|
||
- 时间筛选后相关图层正确重载；
|
||
- 视频监控站与 AI 视频监控站互斥稳定；
|
||
- 菜单切换后图层、图例、筛选项正确重置；
|
||
- 悬停 Popup 与点击详情正常。
|
||
|
||
## 13.2 性能验收指标
|
||
|
||
建议至少跟踪：
|
||
|
||
- 首屏地图可交互时间；
|
||
- 默认勾选图层加载总耗时；
|
||
- 单图层首次加载耗时；
|
||
- 图层勾选后锚点出现时间；
|
||
- 图例点击后的显隐响应时间；
|
||
- 基地切换后的裁切完成时间；
|
||
- 缓存命中率；
|
||
- 页面切换时旧请求是否被取消。
|
||
|
||
## 13.3 自动化测试建议
|
||
|
||
建议补充三类测试：
|
||
|
||
- 单元测试：
|
||
|
||
- 图例派生；
|
||
- 图层互斥规则；
|
||
- 请求解析器；
|
||
- 缓存 key 生成；
|
||
|
||
- 集成测试：
|
||
|
||
- 图层勾选 -> 图例变化 -> 地图显隐；
|
||
- 基地切换 -> 区域裁切 -> 搜索列表更新；
|
||
|
||
- 端到端测试：
|
||
- 地图初始化；
|
||
- 图层切换；
|
||
- 图例切换；
|
||
- 筛选联动；
|
||
- Popup 和详情弹窗。
|
||
|
||
---
|
||
|
||
## 14. 优先级最高的首批改造项
|
||
|
||
如果本轮改造只做最有价值的一批，建议优先按以下顺序处理：
|
||
|
||
1. 修复明显问题：
|
||
|
||
- 去掉 `splice(0, 2)`；
|
||
- 修复 `fetchPointData()` 未定义；
|
||
- 修复 `wq_lineTime` / `wt_lineTime` 未定义；
|
||
- 清理无效代码与重复日志。
|
||
|
||
2. 建立统一状态源：
|
||
|
||
- `selectedLayerKeys`
|
||
- `selectedLegendKeys`
|
||
- `currentBaseId`
|
||
- `currentBaseMapKey`
|
||
|
||
3. 抽离请求解析器和规则引擎：
|
||
|
||
- URL 映射规则统一；
|
||
- 互斥规则统一；
|
||
- 特殊图例补充规则统一。
|
||
|
||
4. 拆 `map.ts`：
|
||
|
||
- 配置状态；
|
||
- 运行状态；
|
||
- 数据缓存；
|
||
- 行为编排。
|
||
|
||
5. 拆 `map.ol.ts`：
|
||
- 底图管理；
|
||
- 锚点管理；
|
||
- Popup 管理；
|
||
- 区域裁切管理。
|
||
|
||
---
|
||
|
||
## 15. 改造后的预期收益
|
||
|
||
完成改造后，地图模块应达到以下效果：
|
||
|
||
- 新增图层和专题能力时，不需要修改多个组件和多个文件；
|
||
- 图层树、图例、地图显隐的状态不再互相打架；
|
||
- 首屏加载更快，图层切换更轻；
|
||
- 地图代码从“堆逻辑”变成“可扩展的稳定结构”；
|
||
- 后续增加 3D 共用逻辑、专题聚合图层、更多筛选条件时，改造成本明显下降。
|
||
|
||
---
|
||
|
||
## 16. 结论
|
||
|
||
当前地图模块功能已经较完整，但代码结构处于“功能可用、结构偏重、规则分散、性能隐患较多”的阶段。继续在现有结构上叠加新需求，后续维护成本会快速上升。
|
||
|
||
建议本次改造不要只做局部优化，而应围绕以下核心原则整体推进：
|
||
|
||
- 单向数据流；
|
||
- 业务规则收口；
|
||
- 渲染层职责下沉；
|
||
- 类型与索引先行；
|
||
- 先止血，再拆层，再提速。
|
||
|
||
按照本文档的分阶段方案推进，可以在不一次性推翻现有功能的前提下，逐步完成地图模块的结构升级。
|