WholeProcessPlatform/frontend/docs/地图模块重构实施清单.md

地图模块重构实施清单

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 建立基础索引

• 建立 layerByKey 索引
• 建立 legendByNameEn 索引
• 建立 legendByLayerCode 索引
• 将 findLayerByKey() 的高频调用逐步替换为索引访问
• 将图例派生中的重复递归改为“初始化索引 + 增量查询”

优先改造位置：

• src/store/modules/map.ts

验收标准：

• 图层查找和图例查找不再完全依赖全量递归；
• 图层勾选、图例切换后响应速度不下降；
• 功能表现与现状一致。

---

4. 阶段二：规则收口

4.1 收口互斥规则

• 将图层互斥逻辑从 LayerController.vue 中移出
• 将视频监控站与 AI 视频监控站互斥统一到规则函数
• 将环保设施与环保设施在建互斥统一到规则函数
• 将珍稀鱼类与沿程鱼类互斥统一到规则函数
• 保证互斥规则只有一个入口执行

建议新增文件：

• src/modules/map/domain/map-layer-rules.ts

涉及文件：

• src/components/mapController/LayerController.vue
• src/store/modules/map.ts

验收标准：

• 图层树勾选时互斥结果稳定；
• 不再同时在组件和 Store 两处维护同一套互斥规则；
• 勾选结果、图例结果、地图显示结果保持一致。

4.2 收口图例派生规则

• 将“图层选中后生成图例”逻辑提炼为独立函数
• 将“环保设施图例自动补充”逻辑提炼为独立规则
• 分离图例原始结构与图例选中状态
• 保证 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 新增地图编排器

• 新增地图模块统一编排入口
• 将地图初始化流程迁移到编排器
• 将图层勾选、图例勾选、基地切换、时间筛选、搜索定位改为统一命令
• 收口 GisView.vue 中的配置加载与监听联动逻辑

建议新增文件：

• src/modules/map/application/map-orchestrator.ts

6.2 统一入口命令

• 定义 initialize(pageKey)
• 定义 toggleLayer(layerKey)
• 定义 toggleLegend(layerKey, legendKey)
• 定义 changeBaseId(baseId)
• 定义 changeTimeRange(range)
• 定义 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 拆分区域过滤管理

• 抽离基地切换后的区域裁切逻辑
• 抽离点在面内判断逻辑
• 抽离区域外锚点显隐逻辑
• 抽离遮罩应用与清理逻辑

建议新增文件：

• src/components/gis/ol/region-mask-manager.ts

验收标准：

• map.ol.ts 文件长度和职责明显收缩；
• 点图层、Popup、基地裁切三类逻辑各自独立；
• 现有地图交互行为不变。

---

8. 阶段六：组件瘦身

8.1 GisView.vue

• 仅保留地图容器、地图初始化调用、组件挂载
• 移除配置请求和复杂 watch 编排逻辑
• 只通过编排器触发初始化和页面切换

8.2 LayerController.vue

• 只保留树渲染与勾选事件
• 移除互斥规则
• 移除基础图层初始化编排逻辑

8.3 MapLegend.vue

• 只保留图例渲染与点击事件分发
• 不直接调用地图实例

8.4 MapFilter.vue

• 只保留表单与用户输入
• 搜索、容量、时间、基地变化全部通过编排器分发
• 不直接修改图例运行态和锚点显隐

验收标准：

• 组件文件职责单一；
• UI 组件中不再出现大段业务逻辑；
• 地图相关行为主要集中在编排层和 Store。

---

9. 阶段七：性能优化

9.1 请求与缓存优化

• 将 GisUrlList.ts 预编译为索引字典，而不是每次请求时重建
• 实现真实请求去重
• 增加请求取消能力，避免菜单切换时旧请求回写
• 对图层加载增加并发控制
• 将缓存 key 与图层 key、筛选条件绑定

9.2 锚点显示优化

• 图例切换时只处理目标图例对应的锚点集合
• 图层切换时优先切换图层可见性，不重复加点
• 减少 hover 时全量点图层重绘
• 减少样式函数中的业务判断复杂度

验收标准：

• 首屏加载时长不高于当前；
• 图层勾选、图例勾选、基地切换响应速度优于当前；
• 菜单快速切换时不出现旧数据回写。

---

10. 回归测试清单

每完成一个阶段，至少回归以下功能：

• 地图初始化正常
• 默认基础图层正常显示
• 图层树勾选与取消勾选正常
• 图例随图层选中动态显示
• 图例点击能正确控制锚点显隐
• 基地切换后区域裁切和锚点过滤正常
• 锚点 hover Popup 正常
• 锚点点击详情弹窗正常
• 时间筛选、容量筛选、搜索定位正常
• 视频监控站与 AI 视频监控站互斥正常
• 菜单切换后地图数据不串页

---

11. 实施顺序建议

推荐严格按以下顺序执行：

1. 阶段一：现状收口与问题修复
2. 阶段二：规则收口
3. 阶段三：拆分 Store
4. 阶段四：建立统一编排层
5. 阶段五：拆分 OpenLayers 渲染层
6. 阶段六：组件瘦身
7. 阶段七：性能优化

不建议直接跳到渲染层拆分或性能优化，否则会在旧结构上重复返工。

---

12. 本轮交付标准

当本清单全部完成后，应达到以下结果：

• 地图模块核心职责划分清晰；
• 图层树、图例、锚点、筛选、基地切换链路可追踪；
• 关键规则不再散落在多个组件里；
• map.ts 和 map.ol.ts 体积明显下降；
• 新增地图业务时有明确扩展点；
• 后续继续做底图体系优化、长期性能建设时不需要再推翻本轮结构。