381 lines
10 KiB
Markdown
381 lines
10 KiB
Markdown
# 地图模块重构实施清单
|
||
|
||
## 1. 使用说明
|
||
|
||
本文档是地图模块重构的执行清单，只保留当前已经明确、可以直接落地的实施项。
|
||
|
||
以下内容暂不纳入本清单：
|
||
|
||
- 仍需进一步讨论的方案；
|
||
- 依赖后端配合后才能确定的优化项；
|
||
- 暂未确定收益与改造成本的预研项；
|
||
- 调试面板、埋点体系、长期性能平台化建设等扩展项。
|
||
|
||
执行原则：
|
||
|
||
- 先止血，再拆层，再提速；
|
||
- 每一步都要保证现有业务可用；
|
||
- 每个阶段结束后都要做功能回归；
|
||
- 不在同一阶段同时改动 UI、Store、地图渲染层的大块逻辑。
|
||
|
||
---
|
||
|
||
## 2. 本轮重构目标
|
||
|
||
本轮只完成以下确定目标：
|
||
|
||
- 收口当前明显缺陷和遗留代码；
|
||
- 建立基础类型和索引；
|
||
- 将分散在组件中的核心业务规则收口；
|
||
- 拆分地图 Store，建立更清晰的数据职责；
|
||
- 抽离统一编排层；
|
||
- 拆分 `map.ol.ts` 的核心管理职责；
|
||
- 保证图层树、图例、锚点显隐链路更清晰；
|
||
- 为后续继续重构预留稳定结构。
|
||
|
||
---
|
||
|
||
## 3. 阶段一：现状收口与问题修复
|
||
|
||
## 3.1 清理明显遗留问题
|
||
|
||
- [ ] 删除 `map.ol.ts` 中无意义代码和重复日志
|
||
- [ ] 清理大段失效注释，保留必要说明
|
||
- [ ] 统一地图相关文件中的临时 `console.log`
|
||
|
||
涉及文件：
|
||
|
||
- `src/components/gis/map.ol.ts`
|
||
|
||
验收标准：
|
||
|
||
- 页面可正常编译；
|
||
- 首次进入地图页面不报错；
|
||
- 控制台不再出现未定义函数或变量错误；
|
||
- 默认图层、图例、锚点仍可正常显示。
|
||
|
||
## 3.2 补充基础类型定义
|
||
|
||
- [ ] 新增地图图层类型定义
|
||
- [ ] 新增图例结构类型定义
|
||
- [ ] 新增锚点数据类型定义
|
||
- [ ] 新增筛选参数类型定义
|
||
- [ ] 为 `map.ts`、`map.class.ts`、`map.ol.ts` 替换第一批高频 `any`
|
||
|
||
建议新增文件：
|
||
|
||
- `src/modules/map/types/map-layer.ts`
|
||
- `src/modules/map/types/map-legend.ts`
|
||
- `src/modules/map/types/map-point.ts`
|
||
- `src/modules/map/types/map-filter.ts`
|
||
|
||
验收标准：
|
||
|
||
- 核心地图模块类型边界可读；
|
||
- 新增类型后不影响现有运行；
|
||
- `map.ts`、`map.ol.ts` 中关键方法参数不再全部使用 `any`。
|
||
|
||
## 3.3 建立基础索引
|
||
|
||
- [x] 建立 `layerByKey` 索引
|
||
- [x] 建立 `legendByNameEn` 索引
|
||
- [x] 建立 `legendByLayerCode` 索引
|
||
- [x] 将 `findLayerByKey()` 的高频调用逐步替换为索引访问
|
||
- [x] 将图例派生中的重复递归改为“初始化索引 + 增量查询”
|
||
|
||
优先改造位置：
|
||
|
||
- `src/store/modules/map.ts`
|
||
|
||
验收标准：
|
||
|
||
- 图层查找和图例查找不再完全依赖全量递归；
|
||
- 图层勾选、图例切换后响应速度不下降；
|
||
- 功能表现与现状一致。
|
||
|
||
---
|
||
|
||
## 4. 阶段二：规则收口
|
||
|
||
## 4.1 收口互斥规则
|
||
|
||
- [x] 将图层互斥逻辑从 `LayerController.vue` 中移出
|
||
- [x] 将视频监控站与 AI 视频监控站互斥统一到规则函数
|
||
- [x] 将环保设施与环保设施在建互斥统一到规则函数
|
||
- [x] 将珍稀鱼类与沿程鱼类互斥统一到规则函数
|
||
- [x] 保证互斥规则只有一个入口执行
|
||
|
||
建议新增文件：
|
||
|
||
- `src/modules/map/domain/map-layer-rules.ts`
|
||
|
||
涉及文件：
|
||
|
||
- `src/components/mapController/LayerController.vue`
|
||
- `src/store/modules/map.ts`
|
||
|
||
验收标准：
|
||
|
||
- 图层树勾选时互斥结果稳定；
|
||
- 不再同时在组件和 Store 两处维护同一套互斥规则；
|
||
- 勾选结果、图例结果、地图显示结果保持一致。
|
||
|
||
## 4.2 收口图例派生规则
|
||
|
||
- [x] 将“图层选中后生成图例”逻辑提炼为独立函数
|
||
- [x] 将“环保设施图例自动补充”逻辑提炼为独立规则
|
||
- [x] 分离图例原始结构与图例选中状态
|
||
- [x] 保证 `legendDataOriginal` 不再被运行态逻辑污染
|
||
|
||
建议新增文件：
|
||
|
||
- `src/modules/map/domain/legend-deriver.ts`
|
||
|
||
涉及文件：
|
||
|
||
- `src/store/modules/map.ts`
|
||
- `src/components/mapLegend/index.vue`
|
||
|
||
验收标准：
|
||
|
||
- 图例显示仍按当前选中图层正确联动；
|
||
- 图例点击后锚点显隐正确；
|
||
- 图例原始结构与运行时状态职责更清晰。
|
||
|
||
---
|
||
|
||
## 5. 阶段三：拆分 Store
|
||
|
||
## 5.1 拆分配置状态
|
||
|
||
- [ ] 抽离图层树配置状态
|
||
- [ ] 抽离图例原始配置状态
|
||
- [ ] 抽离页面地图配置加载逻辑
|
||
|
||
建议新增文件：
|
||
|
||
- `src/modules/map/stores/map-config.store.ts`
|
||
|
||
当前迁移来源：
|
||
|
||
- `src/store/modules/map.ts`
|
||
- `src/api/map.ts`
|
||
|
||
## 5.2 拆分运行状态
|
||
|
||
- [ ] 抽离当前选中图层 key
|
||
- [ ] 抽离当前选中图例 key
|
||
- [ ] 抽离当前基地、时间范围、缩放级别等运行态
|
||
- [ ] 统一“当前地图状态”的唯一来源
|
||
|
||
建议新增文件：
|
||
|
||
- `src/modules/map/stores/map-view.store.ts`
|
||
|
||
## 5.3 拆分数据缓存
|
||
|
||
- [ ] 抽离锚点缓存
|
||
- [ ] 抽离图层加载状态
|
||
- [ ] 抽离锚点合并数据 `pointData`
|
||
- [ ] 为每个图层维护独立 `loading / loaded / error`
|
||
|
||
建议新增文件：
|
||
|
||
- `src/modules/map/stores/map-data.store.ts`
|
||
|
||
验收标准：
|
||
|
||
- 原 `map.ts` 体积明显下降；
|
||
- 配置、运行态、数据缓存职责分离；
|
||
- 现有组件仍可通过兼容方式读取数据；
|
||
- 默认图层、图例、锚点加载不受影响。
|
||
|
||
---
|
||
|
||
## 6. 阶段四：建立统一编排层
|
||
|
||
## 6.1 新增地图编排器
|
||
|
||
- [x] 新增地图模块统一编排入口
|
||
- [x] 将地图初始化流程迁移到编排器
|
||
- [x] 将图层勾选、图例勾选、基地切换、时间筛选、搜索定位改为统一命令
|
||
- [x] 收口 `GisView.vue` 中的配置加载与监听联动逻辑
|
||
|
||
建议新增文件：
|
||
|
||
- `src/modules/map/application/map-orchestrator.ts`
|
||
|
||
## 6.2 统一入口命令
|
||
|
||
- [x] 定义 `initialize(pageKey)`
|
||
- [x] 定义 `toggleLayer(layerKey)`
|
||
- [x] 定义 `toggleLegend(layerKey, legendKey)`
|
||
- [x] 定义 `changeBaseId(baseId)`
|
||
- [x] 定义 `changeTimeRange(range)`
|
||
- [x] 定义 `focusPoint(pointId)`
|
||
|
||
涉及文件：
|
||
|
||
- `src/components/gis/GisView.vue`
|
||
- `src/components/mapController/LayerController.vue`
|
||
- `src/components/mapLegend/index.vue`
|
||
- `src/components/mapFilter/index.vue`
|
||
|
||
验收标准：
|
||
|
||
- 地图相关 UI 组件不再直接拼复杂业务逻辑；
|
||
- 组件交互都通过统一入口触发；
|
||
- 图层树、图例、筛选的联动链路更容易追踪。
|
||
|
||
---
|
||
|
||
## 7. 阶段五：拆分 OpenLayers 渲染层
|
||
|
||
## 7.1 拆分点图层管理
|
||
|
||
- [ ] 从 `map.ol.ts` 中抽离锚点图层创建逻辑
|
||
- [ ] 从 `map.ol.ts` 中抽离锚点显隐逻辑
|
||
- [ ] 从 `map.ol.ts` 中抽离图例控制锚点逻辑
|
||
- [ ] 在点图层管理模块中维护图层注册表
|
||
|
||
建议新增文件：
|
||
|
||
- `src/components/gis/ol/point-layer-manager.ts`
|
||
|
||
当前迁移来源：
|
||
|
||
- `src/components/gis/map.ol.ts`
|
||
|
||
## 7.2 拆分 Popup 管理
|
||
|
||
- [ ] 抽离 `initPopupOverlay()`
|
||
- [ ] 抽离 `detectFeatureAtPixel()`
|
||
- [ ] 抽离 `showPopup()`
|
||
- [ ] 收口 hover 和 click 交互逻辑
|
||
|
||
建议新增文件：
|
||
|
||
- `src/components/gis/ol/popup-manager.ts`
|
||
|
||
## 7.3 拆分区域过滤管理
|
||
|
||
- [x] 抽离基地切换后的区域裁切逻辑
|
||
- [x] 抽离点在面内判断逻辑
|
||
- [x] 抽离区域外锚点显隐逻辑
|
||
- [x] 抽离遮罩应用与清理逻辑
|
||
|
||
建议新增文件：
|
||
|
||
- `src/components/gis/ol/region-mask-manager.ts`
|
||
|
||
验收标准：
|
||
|
||
- `map.ol.ts` 文件长度和职责明显收缩；
|
||
- 点图层、Popup、基地裁切三类逻辑各自独立；
|
||
- 现有地图交互行为不变。
|
||
|
||
---
|
||
|
||
## 8. 阶段六：组件瘦身
|
||
|
||
## 8.1 `GisView.vue`
|
||
|
||
- [x] 仅保留地图容器、地图初始化调用、组件挂载
|
||
- [x] 移除配置请求和复杂 watch 编排逻辑
|
||
- [x] 只通过编排器触发初始化和页面切换
|
||
|
||
## 8.2 `LayerController.vue`
|
||
|
||
- [x] 只保留树渲染与勾选事件
|
||
- [x] 移除互斥规则
|
||
- [x] 移除基础图层初始化编排逻辑
|
||
|
||
## 8.3 `MapLegend.vue`
|
||
|
||
- [x] 只保留图例渲染与点击事件分发
|
||
- [x] 不直接调用地图实例
|
||
|
||
## 8.4 `MapFilter.vue`
|
||
|
||
- [x] 只保留表单与用户输入
|
||
- [x] 搜索、容量、时间、基地变化全部通过编排器分发
|
||
- [x] 不直接修改图例运行态和锚点显隐
|
||
|
||
验收标准：
|
||
|
||
- 组件文件职责单一；
|
||
- UI 组件中不再出现大段业务逻辑；
|
||
- 地图相关行为主要集中在编排层和 Store。
|
||
|
||
---
|
||
|
||
## 9. 阶段七：性能优化
|
||
|
||
## 9.1 请求与缓存优化
|
||
|
||
- [x] 将 `GisUrlList.ts` 预编译为索引字典，而不是每次请求时重建
|
||
- [x] 实现真实请求去重
|
||
- [x] 增加请求取消能力，避免菜单切换时旧请求回写
|
||
- [x] 对图层加载增加并发控制
|
||
- [x] 将缓存 key 与图层 key、筛选条件绑定
|
||
|
||
## 9.2 锚点显示优化
|
||
|
||
- [x] 图例切换时只处理目标图例对应的锚点集合
|
||
- [x] 图层切换时优先切换图层可见性，不重复加点
|
||
- [x] 减少 hover 时全量点图层重绘
|
||
- [x] 减少样式函数中的业务判断复杂度
|
||
|
||
验收标准：
|
||
|
||
- 首屏加载时长不高于当前；
|
||
- 图层勾选、图例勾选、基地切换响应速度优于当前；
|
||
- 菜单快速切换时不出现旧数据回写。
|
||
|
||
---
|
||
|
||
## 10. 回归测试清单
|
||
|
||
每完成一个阶段，至少回归以下功能：
|
||
|
||
- [x] 地图初始化正常
|
||
- [x] 默认基础图层正常显示
|
||
- [x] 图层树勾选与取消勾选正常
|
||
- [x] 图例随图层选中动态显示
|
||
- [x] 图例点击能正确控制锚点显隐
|
||
- [x] 基地切换后区域裁切和锚点过滤正常
|
||
- [x] 锚点 hover Popup 正常
|
||
- [x] 锚点点击详情弹窗正常
|
||
- [x] 时间筛选、容量筛选、搜索定位正常
|
||
- [x] 视频监控站与 AI 视频监控站互斥正常
|
||
- [x] 菜单切换后地图数据不串页
|
||
|
||
---
|
||
|
||
## 11. 实施顺序建议
|
||
|
||
推荐严格按以下顺序执行：
|
||
|
||
1. 阶段一：现状收口与问题修复
|
||
2. 阶段二：规则收口
|
||
3. 阶段三：拆分 Store
|
||
4. 阶段四：建立统一编排层
|
||
5. 阶段五：拆分 OpenLayers 渲染层
|
||
6. 阶段六：组件瘦身
|
||
7. 阶段七：性能优化
|
||
|
||
不建议直接跳到渲染层拆分或性能优化，否则会在旧结构上重复返工。
|
||
|
||
---
|
||
|
||
## 12. 本轮交付标准
|
||
|
||
当本清单全部完成后，应达到以下结果：
|
||
|
||
- 地图模块核心职责划分清晰；
|
||
- 图层树、图例、锚点、筛选、基地切换链路可追踪；
|
||
- 关键规则不再散落在多个组件里；
|
||
- `map.ts` 和 `map.ol.ts` 体积明显下降；
|
||
- 新增地图业务时有明确扩展点；
|
||
- 后续继续做底图体系优化、长期性能建设时不需要再推翻本轮结构。
|