# 地图模块重构实施清单 ## 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` 体积明显下降； - 新增地图业务时有明确扩展点； - 后续继续做底图体系优化、长期性能建设时不需要再推翻本轮结构。