ibs-fullstack/docs/plans/2026-02-28-featured-area-customer-view-design.md

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

## 文档信息

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

## 1. 概述

### 1.1 背景

数字支行辅助管理系统的区域绘制功能包含两种区域类型：
1. **行政区域**（btnType=1）：使用 index.vue 页面，区域详情窗口已有"查看客户"按钮
2. **特色区域**（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. 引入组件**

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

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

**2. 添加组件引用**

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

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

**3. 添加图标按钮**

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

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

**4. 添加方法**

```javascript
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 长期优化（可选）

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

## 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 | 初始版本 |