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

- 在特色区域详情窗口添加查看客户按钮的设计方案 - 包含需求分析、技术设计、实施计划、测试计划等内容
2026-02-28 16:01:19 +08:00
parent 7efc23dfd2
commit 8d2e5386ac
1 changed files with 308 additions and 0 deletions
--- a/docs/plans/2026-02-28-featured-area-customer-view-design.md
+++ b/docs/plans/2026-02-28-featured-area-customer-view-design.md
@@ -0,0 +1,308 @@
+# 特色区域详情窗口添加查看客户功能设计文档
+
+## 文档信息
+
+- **日期**: 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 | 初始版本 |