From 8d2e5386aca984615ee68dbbc1cc23afac6bbb7f Mon Sep 17 00:00:00 2001 From: wkc <978997012@qq.com> Date: Sat, 28 Feb 2026 16:01:19 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=89=B9=E8=89=B2?= =?UTF-8?q?=E5=8C=BA=E5=9F=9F=E6=9F=A5=E7=9C=8B=E5=AE=A2=E6=88=B7=E5=8A=9F?= =?UTF-8?q?=E8=83=BD=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在特色区域详情窗口添加查看客户按钮的设计方案 - 包含需求分析、技术设计、实施计划、测试计划等内容 --- ...2-28-featured-area-customer-view-design.md | 308 ++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 docs/plans/2026-02-28-featured-area-customer-view-design.md diff --git a/docs/plans/2026-02-28-featured-area-customer-view-design.md b/docs/plans/2026-02-28-featured-area-customer-view-design.md new file mode 100644 index 0000000..98e8a63 --- /dev/null +++ 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 + +``` + +**3. 添加图标按钮** + +在区域详情窗口的按钮区域（第221-270行），建议位置在"修改信息"按钮之后： + +```vue + + + +``` + +**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 | 初始版本 |