feat(featured-areas): 实现 previewCustomer 方法

- 详细的6个任务分解
- 每个步骤包含具体代码和验证方法
- 包含完整的测试流程
- 包含回滚方案

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

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

@@ -0,0 +1,389 @@
+# 特色区域查看客户功能实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**目标:** 在特色区域详情窗口添加"查看客户"图标按钮，复用现有的 customer-modal 组件，实现客户列表查看功能。
+
+**架构:** 组件复用架构 - BMapPolygonEditor.vue 引入 CustomerModal.vue，通过 refs 调用模态框的 onOpen() 方法。
+
+**技术栈:** Vue 2.x, Element UI, 若依框架
+
+**设计文档:** `docs/plans/2026-02-28-featured-area-customer-view-design.md`
+
+---
+
+## 任务 1: 引入 CustomerModal 组件
+
+**文件:**
+- 修改: `ruoyi-ui/src/map/BMapPolygonEditor.vue:20-30`（import 区域）
+
+**步骤 1: 在 script 标签内添加 import 语句**
+
+在第22行（MenuEdit 导入语句之后）添加：
+
+```javascript
+import CustomerModal from "@/views/grid/map/draw-area/customer-modal.vue"
+```
+
+**步骤 2: 在 components 中注册组件**
+
+在第26-30行的 components 对象中添加 CustomerModal：
+
+```javascript
+components: {
+  MenuEdit,
+  BMapPolygonEditor,
+  MenuEdit,
+  CustomerModal,  // 新增
+},
+```
+
+**步骤 3: 验证 import 路径正确**
+
+运行前端项目验证无报错：
+
+```bash
+cd ruoyi-ui
+npm run dev
+```
+
+预期: 浏览器控制台无 "Failed to mount component" 错误
+
+**步骤 4: 提交代码**
+
+```bash
+git add ruoyi-ui/src/map/BMapPolygonEditor.vue
+git commit -m "feat(featured-areas): 引入 CustomerModal 组件"
+```
+
+---
+
+## 任务 2: 在 template 中添加组件引用
+
+**文件:**
+- 修改: `ruoyi-ui/src/map/BMapPolygonEditor.vue:270-275`（template 末尾）
+
+**步骤 1: 在 template 末尾添加组件标签**
+
+在第273行（`</transition>` 之后，`<div class="search-box">` 之前）添加：
+
+```vue
+    </transition>
+    <!-- 查看客户模态框 -->
+    <customer-modal
+      ref="customerModal"
+      cardType="featured"
+      :detailInfo="areaForm"
+      :btnType="'2'"
+    />
+    <div class="search-box">
+```
+
+**步骤 2: 验证组件引用**
+
+在浏览器中打开特色区域页面，验证控制台无报错。
+
+**步骤 3: 验证 props 传递**
+
+在 Vue DevTools 中检查 customer-modal 组件的 props：
+- cardType 应该是 "featured"
+- detailInfo 应该是 areaForm 对象
+- btnType 应该是 "2"
+
+**步骤 4: 提交代码**
+
+```bash
+git add ruoyi-ui/src/map/BMapPolygonEditor.vue
+git commit -m "feat(featured-areas): 添加 CustomerModal 组件引用"
+```
+
+---
+
+## 任务 3: 在区域详情窗口添加查看客户图标按钮
+
+**文件:**
+- 修改: `ruoyi-ui/src/map/BMapPolygonEditor.vue:221-240`（edit-operate 按钮区域）
+
+**步骤 1: 定位按钮插入位置**
+
+找到第221-240行的代码区域，这是 `infoType === 'SHOW'` 的按钮区域：
+- 第229行：修改信息按钮结束
+- 第240行：删除区域按钮开始
+
+我们需要在修改信息按钮之后插入查看客户按钮。
+
+**步骤 2: 添加查看客户图标按钮**
+
+在第239行（修改信息 tooltip 结束）之后，第240行（删除区域 tooltip 开始）之前插入：
+
+```vue
+            </el-tooltip>
+            <!-- 查看客户 -->
+            <el-tooltip placement="top" effect="light" content="查看客户">
+              <i
+                class="el-icon-user icon-area"
+                @click.stop="previewCustomer"
+              />
+            </el-tooltip>
+            <!-- 删除区域 -->
+            <el-tooltip placement="top" effect="light" content="删除区域">
+```
+
+**步骤 3: 验证图标样式**
+
+在浏览器中：
+1. 打开特色区域页面
+2. 点击一个已绘制的区域
+3. 查看区域详情窗口底部的图标按钮区域
+4. 验证新添加的"用户图标"样式与其他图标一致
+
+**步骤 4: 验证 tooltip 显示**
+
+1. 鼠标悬停在新添加的用户图标上
+2. 验证 tooltip 显示"查看客户"
+3. 验证 tooltip 样式与其他 tooltip 一致
+
+**步骤 5: 提交代码**
+
+```bash
+git add ruoyi-ui/src/map/BMapPolygonEditor.vue
+git commit -m "feat(featured-areas): 添加查看客户图标按钮"
+```
+
+---
+
+## 任务 4: 实现 previewCustomer 方法
+
+**文件:**
+- 修改: `ruoyi-ui/src/map/BMapPolygonEditor.vue:900-1000`（methods 区域）
+
+**步骤 1: 定位 methods 区域**
+
+找到 methods 对象的最后，准备添加新方法。建议添加在 `updateAreaShape()` 方法之后。
+
+**步骤 2: 添加 previewCustomer 方法**
+
+在 methods 对象中添加：
+
+```javascript
+    /**
+     * 调整边界
+     */
+    updateAreaShape() {
+      // ... 现有代码
+    },
+    /**
+     * 查看客户
+     */
+    previewCustomer() {
+      this.$refs.customerModal.onOpen()
+    }
+```
+
+**步骤 3: 验证方法调用**
+
+在浏览器控制台中测试：
+1. 打开特色区域页面
+2. 点击一个区域，打开区域详情窗口
+3. 打开 Vue DevTools
+4. 找到 BMapPolygonEditor 组件
+5. 在控制台执行：`$vm0.previewCustomer()`
+6. 验证 customer-modal 模态框成功打开
+
+**步骤 4: 提交代码**
+
+```bash
+git add ruoyi-ui/src/map/BMapPolygonEditor.vue
+git commit -m "feat(featured-areas): 实现 previewCustomer 方法"
+```
+
+---
+
+## 任务 5: 功能测试
+
+**文件:**
+- 无需修改文件
+
+**步骤 1: 启动前端项目**
+
+```bash
+cd ruoyi-ui
+npm run dev
+```
+
+预期: 项目成功启动在 http://localhost:80
+
+**步骤 2: 登录系统**
+
+1. 访问 http://localhost:80
+2. 使用测试账号登录：
+   - 用户名: admin
+   - 密码: admin123
+
+**步骤 3: 进入特色区域页面**
+
+1. 导航到"网格管理" > "区域绘制"
+2. 点击"特色区域"标签（btnType=2）
+3. 等待地图加载完成
+
+**步骤 4: 测试查看客户按钮**
+
+1. 在左侧菜单中选择一个特色区域图层
+2. 在地图上点击一个已绘制的特色区域
+3. 验证右上角弹出区域详情窗口
+4. 查看窗口底部的图标按钮区域
+5. 验证显示"用户图标"（查看客户按钮）
+
+**步骤 5: 测试点击功能**
+
+1. 点击"查看客户"图标
+2. 验证：
+   - customer-modal 对话框成功打开
+   - 对话框标题显示"查看客户"
+   - 顶部显示区域名称和规模信息
+   - 客户列表成功加载
+   - 显示三种客户类型标签（企业/个人/商户）
+
+**步骤 6: 测试客户类型切换**
+
+1. 点击"个人"标签
+2. 验证客户列表刷新，显示个人客户
+3. 点击"商户"标签
+4. 验证客户列表刷新，显示商户客户
+5. 点击"企业"标签
+6. 验证客户列表刷新，显示企业客户
+
+**步骤 7: 测试分页功能**
+
+1. 如果客户数量超过10条，验证分页器显示
+2. 点击下一页
+3. 验证客户列表刷新，显示第二页数据
+4. 修改每页显示条数
+5. 验证列表重新加载
+
+**步骤 8: 测试客户详情跳转**
+
+1. 点击表格中的客户名称（el-button）
+2. 验证路由跳转到客户详情页面
+3. 验证详情页面显示正确的客户信息
+
+**步骤 9: 测试现有功能兼容性**
+
+1. 关闭客户模态框
+2. 依次点击其他4个图标按钮：
+   - 重新申请
+   - 修改信息
+   - 删除区域
+   - 调整边界
+3. 验证这些按钮功能正常，无报错
+
+**步骤 10: 测试行政区域兼容性**
+
+1. 切换到"行政区域"标签（btnType=1）
+2. 点击一个行政区域
+3. 验证行政区域的"查看客户"按钮功能正常
+4. 验证两个区域类型的查看客户功能互不影响
+
+**步骤 11: 检查浏览器控制台**
+
+1. 打开浏览器开发者工具
+2. 切换到 Console 标签
+3. 执行所有测试步骤
+4. 验证控制台无 JavaScript 报错
+5. 验证控制台无 Vue 警告
+
+**步骤 12: 最终提交**
+
+如果所有测试通过：
+
+```bash
+git status
+```
+
+预期: 无未提交的文件
+
+---
+
+## 任务 6: 更新文档（可选）
+
+**文件:**
+- 修改: `docs/plans/2026-02-28-featured-area-customer-view-design.md`
+
+**步骤 1: 更新验收标准**
+
+在验收标准的各项前打勾：
+
+```markdown
+### 6.1 功能验收
+
+- [x] 区域详情窗口中显示"查看客户"图标按钮
+- [x] 点击按钮后成功打开客户查看模态框
+- [x] 模态框顶部显示正确的区域名称和规模
+- [x] 客户列表正确加载（企业/个人/商户三种类型）
+- [x] 客户类型切换功能正常
+- [x] 分页功能正常
+- [x] 点击客户名称可跳转到客户详情页
+
+### 6.2 UI验收
+
+- [x] 图标样式与现有图标按钮一致
+- [x] 图标大小、颜色、间距合理
+- [x] Tooltip 正确显示"查看客户"
+- [x] 图标位置合理，不拥挤
+
+### 6.3 性能验收
+
+- [x] 页面加载速度无明显变化
+- [x] 模态框打开速度正常（<1秒）
+- [x] 客户列表加载速度正常（<2秒）
+
+### 6.4 兼容性验收
+
+- [x] 现有4个图标按钮功能正常
+- [x] 行政区域的查看客户功能正常
+- [x] 浏览器控制台无报错
+```
+
+**步骤 2: 提交文档更新**
+
+```bash
+git add docs/plans/2026-02-28-featured-area-customer-view-design.md
+git commit -m "docs: 更新特色区域查看客户功能验收状态"
+```
+
+---
+
+## 完成检查清单
+
+实施完成后，验证以下内容：
+
+- [ ] 所有6个任务已完成
+- [ ] 所有 git commits 已提交
+- [ ] 前端项目无编译错误
+- [ ] 浏览器控制台无 JavaScript 错误
+- [ ] 功能测试全部通过
+- [ ] 代码已推送到远程仓库（如需要）
+
+## 回滚方案
+
+如果实施过程中遇到问题，可以回滚：
+
+```bash
+# 查看提交历史
+git log --oneline
+
+# 回滚到指定提交（替换 <commit-hash> 为实际的 commit hash）
+git reset --hard <commit-hash>
+
+# 或者回滚所有提交（回到初始状态）
+git reset --hard HEAD~4
+```
+
+## 相关资源
+
+- **设计文档**: `docs/plans/2026-02-28-featured-area-customer-view-design.md`
+- **修改文件**: `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:413-416`
+- **Element UI 文档**: https://element.eleme.cn/#/zh-CN/component/tooltip
+- **Vue 2.x 文档**: https://v2.cn.vuejs.org/

ruoyi-ui/src/map/BMapPolygonEditor.vue

@@ -237,6 +237,14 @@
                 @click.stop="updateAreaInfo"
               />
             </el-tooltip>
+            <!-- 查看客户 -->
+            <el-tooltip placement="top" effect="light" content="查看客户">
+              <i
+                class="el-icon-user icon-area"
+                @click.stop="previewCustomer"
+              />
+            </el-tooltip>
+            <!-- 删除区域 -->
             <el-tooltip placement="top" effect="light" content="删除区域">
               <el-popconfirm
                 title="确定删除吗？"
@@ -271,6 +279,13 @@
         </div>
       </div>
     </transition>
+    <!-- 查看客户模态框 -->
+    <customer-modal
+      ref="customerModal"
+      cardType="featured"
+      :detailInfo="areaForm"
+      :btnType="'2'"
+    />
     <div class="search-box">
       <el-form size="small" class="myForm">
         <el-form-item style="width: 130px">
@@ -337,6 +352,7 @@ import { businessBelongList } from '@/views/grid/create/utils'
 import { mapGetters } from 'vuex'
 import { Message } from 'element-ui'
 import { isEmpty } from 'lodash'
+import CustomerModal from '@/views/grid/map/draw-area/customer-modal.vue'
 const polygonOptions = {
   strokeColor: '#5E87DB',
   strokeWeight: 3,
@@ -355,6 +371,9 @@ const labelOptions = {
 }
 export default {
   name: 'BMapPolygonEditor',
+  components: {
+    CustomerModal
+  },
   props: ['layerInfo'],
   data() {
     return {
@@ -1207,6 +1226,12 @@ export default {
       this.$store.dispatch('setIsDrawing', true)
       this.currentPolygon.enableEditing()
     },
+    /**
+     * 查看客户
+     */
+    previewCustomer() {
+      this.$refs.customerModal.onOpen()
+    },
     setForm(data) {
       this.areaForm = data
       this.visible = true