Files

wkc 8d2e5386ac docs: 添加特色区域查看客户功能设计文档

- 在特色区域详情窗口添加查看客户按钮的设计方案
- 包含需求分析、技术设计、实施计划、测试计划等内容

2026-02-28 16:01:19 +08:00

8.1 KiB

Raw Permalink Blame History

特色区域详情窗口添加查看客户功能设计文档

文档信息

日期: 2026-02-28
作者: Claude Code
模块: 区域绘制 - 特色区域
需求来源: 用户需求

1. 概述

1.1 背景

数字支行辅助管理系统的区域绘制功能包含两种区域类型：

行政区域（btnType=1）：使用 index.vue 页面，区域详情窗口已有"查看客户"按钮
特色区域（btnType=2）：使用 BMapPolygonEditor.vue 组件，区域详情窗口缺少"查看客户"功能

1.2 目标

在特色区域的区域详情窗口中，添加"查看客户"按钮，使功能与行政区域保持一致，方便用户快速查看该区域内的客户信息。

1.3 范围

涉及模块：

前端：ruoyi-ui/src/map/BMapPolygonEditor.vue
复用组件：ruoyi-ui/src/views/grid/map/draw-area/customer-modal.vue

不涉及：

后端 API 修改
数据库修改
新增文件

2. 需求分析

2.1 用户需求

在区域绘制的特色区域详情窗口内，添加一个查看客户的按钮，功能与特色区域列表（menulist-modal）中的查看客户功能保持一致。

2.2 功能需求

必须实现（MVP）

✅ 在区域详情窗口的按钮区域添加"查看客户"图标按钮
✅ 点击按钮后打开客户查看模态框
✅ 模态框中显示该特色区域的企业、个人、商户客户列表
✅ 支持客户类型切换（企业/个人/商户）
✅ 支持分页查询
✅ 支持点击客户名称跳转到客户详情页

可选功能

2.3 非功能需求

性能: 不影响页面加载速度
易用性: 图标按钮风格与现有按钮保持一致
兼容性: 不影响现有功能
可维护性: 代码结构清晰，复用现有组件

3. 技术设计

3.1 整体架构

采用组件复用架构：

展示层: BMapPolygonEditor.vue（特色区域地图编辑器）
组件层: CustomerModal.vue（客户查看模态框，已存在）
数据层: API 接口（shapeCustList，已存在）

3.2 方案选择

经过方案对比分析，选择方案1：添加图标按钮

方案对比：

方案	优点	缺点	评分
方案1：图标按钮	UI风格一致、改动最小、实现简单	图标不如文字明显	★★★★★
方案2：文字按钮	按钮明显、文字清晰	可能破坏布局、需要调整样式	★★★☆☆
方案3：替换布局	与行政区域一致	改动大、影响用户体验	★★☆☆☆

3.3 数据流程

用户操作流程:
用户点击特色区域
  ↓
显示区域详情窗口（area-info-modal）
  ↓
用户点击"查看客户"图标按钮
  ↓
触发 previewCustomer() 方法
  ↓
调用 this.$refs.customerModal.onOpen()
  ↓
CustomerModal 组件接收参数:
  - cardType="featured" (标识特色区域)
  - :detailInfo="areaForm" (包含 shapeId)
  - :btnType="'2'" (特色区域类型)
  ↓
CustomerModal 调用 shapeCustList API
  ↓
获取并展示客户列表数据
  ↓
用户可切换客户类型（企业/个人/商户）
  ↓
用户可点击客户名称查看详情

3.4 接口设计

使用现有接口：

获取特色区域客户列表

接口: shapeCustList
文件: @/api/grid/draw-area.js
参数:
- shapeId: 区域ID
- pageNum: 页码
- pageSize: 每页条数
- custType: 客户类型（0=个人，1=商户，2=企业）
返回: 客户列表数据

无需新增接口。

3.5 组件设计

BMapPolygonEditor.vue 修改

1. 引入组件

import CustomerModal from "@/views/grid/map/draw-area/customer-modal.vue"

export default {
  components: {
    // ... 现有组件
    CustomerModal,
  },
}

2. 添加组件引用

在 template 末尾（约第273行之后）添加：

<customer-modal
  ref="customerModal"
  cardType="featured"
  :detailInfo="areaForm"
  :btnType="'2'"
/>

3. 添加图标按钮

在区域详情窗口的按钮区域（第221-270行），建议位置在"修改信息"按钮之后：

<el-tooltip placement="top" effect="light" content="查看客户">
  <i
    class="el-icon-user icon-area"
    @click.stop="previewCustomer"
  />
</el-tooltip>

4. 添加方法

methods: {
  // ... 现有方法

  /**
   * 查看客户
   */
  previewCustomer() {
    this.$refs.customerModal.onOpen()
  }
}

CustomerModal.vue（无需修改）

该组件已实现完整的客户查看功能：

支持行政区域（通过 code 查询）
支持特色区域（通过 shapeId 查询）
支持三种客户类型切换
支持分页
支持跳转客户详情

4. 实施计划

4.1 开发任务

任务	文件	预估时间	负责人
添加"查看客户"功能	BMapPolygonEditor.vue	0.5h	前端开发
功能测试	-	0.5h	测试人员

总计: 1小时

4.2 测试计划

单元测试

测试 previewCustomer() 方法是否正确调用
测试组件引用是否正确传递参数

集成测试

测试点击按钮后模态框是否正常打开
测试客户列表是否正确加载
测试客户类型切换功能
测试分页功能

UI测试

测试图标样式是否一致
测试 tooltip 是否正确显示
测试响应式布局

回归测试

验证现有4个图标按钮功能正常
验证行政区域的查看客户功能正常
验证页面无报错

4.3 部署计划

开发环境: 开发完成后立即部署测试
测试环境: 通过代码审查后部署
生产环境: 测试通过后部署

5. 风险评估

5.1 技术风险

风险	等级	影响	缓解措施
组件引入导致页面加载变慢	低	轻微	组件已在使用，无额外性能影响
图标样式不一致	低	轻微	使用现有 icon-area 样式类
数据传递错误	中	中等	充分测试，确保 shapeId 正确传递

5.2 业务风险

风险	等级	影响	缓解措施
用户体验变化	低	轻微	仅新增功能，不影响现有操作
功能误解	低	轻微	tooltip 提示清晰

6. 验收标准

6.1 功能验收

区域详情窗口中显示"查看客户"图标按钮
点击按钮后成功打开客户查看模态框
模态框顶部显示正确的区域名称和规模
客户列表正确加载（企业/个人/商户三种类型）
客户类型切换功能正常
分页功能正常
点击客户名称可跳转到客户详情页

6.2 UI验收

图标样式与现有图标按钮一致
图标大小、颜色、间距合理
Tooltip 正确显示"查看客户"
图标位置合理，不拥挤

6.3 性能验收

页面加载速度无明显变化
模态框打开速度正常（<1秒）
客户列表加载速度正常（<2秒）

6.4 兼容性验收

现有4个图标按钮功能正常
行政区域的查看客户功能正常
浏览器控制台无报错

7. 后续优化

7.1 短期优化（可选）

7.2 长期优化（可选）

统一按钮风格: 考虑将所有图标按钮改为文字按钮，提高可读性
权限控制: 根据用户角色控制"查看客户"按钮的显示/隐藏
数据缓存: 对频繁查看的区域客户数据进行缓存，提升加载速度

8. 附录

8.1 相关文件

ruoyi-ui/src/map/BMapPolygonEditor.vue - 特色区域地图编辑器
ruoyi-ui/src/views/grid/map/draw-area/customer-modal.vue - 客户查看模态框
ruoyi-ui/src/views/grid/map/draw-area/components/menulist-modal.vue - 特色区域列表
ruoyi-ui/src/views/grid/map/draw-area/index.vue - 行政区域页面

8.2 参考资料

Element UI 文档: https://element.eleme.cn/
若依框架文档: http://doc.ruoyi.vip/

8.3 变更记录

版本	日期	修改人	修改内容
1.0	2026-02-28	Claude Code	初始版本

8.1 KiB Raw Permalink Blame History Unescape Escape