docs: 添加项目管理页面改进设计文档
- 搜索框添加内嵌搜索按钮 - 标签页状态计数改为后端统计接口 - 状态标签改为简约小圆点样式
This commit is contained in:
586
docs/plans/2026-02-27-project-management-improvements-design.md
Normal file
586
docs/plans/2026-02-27-project-management-improvements-design.md
Normal file
@@ -0,0 +1,586 @@
|
||||
# 项目管理页面改进设计文档
|
||||
|
||||
**日期：** 2026-02-27
|
||||
**作者：** Claude Code
|
||||
**状态：** 待实施
|
||||
|
||||
---
|
||||
|
||||
## 一、需求概述
|
||||
|
||||
项目管理页面存在以下三个问题需要改进：
|
||||
|
||||
1. **搜索框缺少搜索按钮** - 用户只能通过回车或清空触发搜索，缺少显式的搜索按钮
|
||||
2. **标签页状态计数不准确** - 当前只统计当前页的数据，无法反映全局状态分布
|
||||
3. **状态标签样式不够简约** - 当前使用带背景色的标签，视觉上较重
|
||||
|
||||
---
|
||||
|
||||
## 二、技术方案
|
||||
|
||||
### 2.1 方案选择
|
||||
|
||||
经过对比分析，选择 **方案1：独立统计接口 + 精准样式改造**
|
||||
|
||||
**理由：**
|
||||
- 接口职责单一，易于维护
|
||||
- 统计数据准确，不受分页影响
|
||||
- 性能最优，统计数据量小（仅4个数字）
|
||||
- 符合 RESTful 设计规范
|
||||
|
||||
---
|
||||
|
||||
## 三、后端设计
|
||||
|
||||
### 3.1 新增统计接口
|
||||
|
||||
**接口定义**
|
||||
|
||||
```
|
||||
GET /ccdi/project/statusCounts
|
||||
```
|
||||
|
||||
**权限要求**
|
||||
|
||||
```
|
||||
ccdi:project:list
|
||||
```
|
||||
|
||||
**Controller 层实现**
|
||||
|
||||
文件：`ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectController.java`
|
||||
|
||||
```java
|
||||
/**
|
||||
* 获取项目状态统计
|
||||
*/
|
||||
@GetMapping("/statusCounts")
|
||||
@Operation(summary = "获取项目状态统计")
|
||||
@PreAuthorize("@ss.hasPermi('ccdi:project:list')")
|
||||
public AjaxResult getStatusCounts() {
|
||||
Map<String, Long> counts = projectService.getStatusCounts();
|
||||
return AjaxResult.success(counts);
|
||||
}
|
||||
```
|
||||
|
||||
**Service 层接口**
|
||||
|
||||
文件：`ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectService.java`
|
||||
|
||||
```java
|
||||
/**
|
||||
* 获取各状态的项目数量
|
||||
* @return 返回格式：{"all": 总数, "0": 进行中数量, "1": 已完成数量, "2": 已归档数量}
|
||||
*/
|
||||
Map<String, Long> getStatusCounts();
|
||||
```
|
||||
|
||||
**Service 层实现**
|
||||
|
||||
文件：`ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java`
|
||||
|
||||
```java
|
||||
@Override
|
||||
public Map<String, Long> getStatusCounts() {
|
||||
Map<String, Long> counts = new HashMap<>();
|
||||
|
||||
// 使用 MyBatis Plus 分组查询
|
||||
QueryWrapper<CcdiProject> wrapper = new QueryWrapper<>();
|
||||
wrapper.select("status", "COUNT(*) as count")
|
||||
.groupBy("status");
|
||||
|
||||
List<Map<String, Object>> results = baseMapper.selectMaps(wrapper);
|
||||
|
||||
// 初始化各状态计数
|
||||
Long totalCount = 0L;
|
||||
Long inProgressCount = 0L;
|
||||
Long completedCount = 0L;
|
||||
Long archivedCount = 0L;
|
||||
|
||||
// 遍历结果统计
|
||||
for (Map<String, Object> result : results) {
|
||||
String status = (String) result.get("status");
|
||||
Long count = (Long) result.get("count");
|
||||
|
||||
totalCount += count;
|
||||
if ("0".equals(status)) {
|
||||
inProgressCount = count;
|
||||
} else if ("1".equals(status)) {
|
||||
completedCount = count;
|
||||
} else if ("2".equals(status)) {
|
||||
archivedCount = count;
|
||||
}
|
||||
}
|
||||
|
||||
counts.put("all", totalCount);
|
||||
counts.put("0", inProgressCount);
|
||||
counts.put("1", completedCount);
|
||||
counts.put("2", archivedCount);
|
||||
|
||||
return counts;
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"all": 15,
|
||||
"0": 8,
|
||||
"1": 5,
|
||||
"2": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、前端设计
|
||||
|
||||
### 4.1 API 接口定义
|
||||
|
||||
**文件：** `ruoyi-ui/src/api/ccdiProject.js`
|
||||
|
||||
```javascript
|
||||
// 获取项目状态统计
|
||||
export function getProjectStatusCounts() {
|
||||
return request({
|
||||
url: '/ccdi/project/statusCounts',
|
||||
method: 'get'
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 SearchBar 组件改造
|
||||
|
||||
**文件：** `ruoyi-ui/src/views/ccdiProject/components/SearchBar.vue`
|
||||
|
||||
**改动说明：**
|
||||
- 使用 Element UI 的 slot 功能在输入框右侧添加搜索按钮
|
||||
- 保持回车和清空触发搜索的功能
|
||||
- 调整输入框宽度以容纳按钮
|
||||
|
||||
**实现代码：**
|
||||
|
||||
```vue
|
||||
<el-input
|
||||
v-model="searchKeyword"
|
||||
placeholder="请输入关键词搜索项目"
|
||||
clearable
|
||||
size="small"
|
||||
class="search-input"
|
||||
@keyup.enter.native="handleSearch"
|
||||
@clear="handleSearch"
|
||||
>
|
||||
<el-button
|
||||
slot="append"
|
||||
icon="el-icon-search"
|
||||
@click="handleSearch"
|
||||
/>
|
||||
</el-input>
|
||||
```
|
||||
|
||||
**样式调整：**
|
||||
|
||||
```scss
|
||||
.search-input {
|
||||
width: 300px; // 从 240px 调整为 300px
|
||||
height: 40px;
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 ProjectTable 组件改造
|
||||
|
||||
**文件：** `ruoyi-ui/src/views/ccdiProject/components/ProjectTable.vue`
|
||||
|
||||
**改动说明：**
|
||||
- 替换 `<el-tag>` + `<dict-tag>` 组合为简约的小圆点样式
|
||||
- 使用不同颜色的小圆点标识不同状态
|
||||
- 文字统一使用黑色，降低视觉干扰
|
||||
|
||||
**实现代码：**
|
||||
|
||||
```vue
|
||||
<!-- 状态列 -->
|
||||
<el-table-column
|
||||
prop="status"
|
||||
label="状态"
|
||||
width="120"
|
||||
align="center"
|
||||
>
|
||||
<template slot-scope="scope">
|
||||
<span class="status-badge" :class="'status-' + scope.row.status">
|
||||
<span class="status-dot"></span>
|
||||
<span class="status-text">{{ getStatusText(scope.row.status) }}</span>
|
||||
</span>
|
||||
</template>
|
||||
</el-table-column>
|
||||
```
|
||||
|
||||
**新增方法：**
|
||||
|
||||
```javascript
|
||||
getStatusText(status) {
|
||||
const statusMap = {
|
||||
'0': '进行中',
|
||||
'1': '已完成',
|
||||
'2': '已归档'
|
||||
}
|
||||
return statusMap[status] || '未知'
|
||||
}
|
||||
```
|
||||
|
||||
**移除方法：**
|
||||
|
||||
```javascript
|
||||
// 删除不再使用的 getStatusType 方法
|
||||
```
|
||||
|
||||
**样式设计：**
|
||||
|
||||
```scss
|
||||
.status-badge {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
|
||||
.status-dot {
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
border-radius: 50%;
|
||||
display: inline-block;
|
||||
}
|
||||
|
||||
.status-text {
|
||||
color: #333;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
// 进行中 - 蓝色
|
||||
&.status-0 .status-dot {
|
||||
background-color: #1890ff;
|
||||
}
|
||||
|
||||
// 已完成 - 绿色
|
||||
&.status-1 .status-dot {
|
||||
background-color: #52c41a;
|
||||
}
|
||||
|
||||
// 已归档 - 灰色
|
||||
&.status-2 .status-dot {
|
||||
background-color: #8c8c8c;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 主页面集成
|
||||
|
||||
**文件：** `ruoyi-ui/src/views/ccdiProject/index.vue`
|
||||
|
||||
**改动说明：**
|
||||
- 引入统计接口
|
||||
- created 生命周期并发加载统计和列表数据
|
||||
- 状态变更后同时刷新统计和列表
|
||||
- 优雅的错误处理
|
||||
|
||||
**引入接口：**
|
||||
|
||||
```javascript
|
||||
import { listProject, getProjectStatusCounts } from '@/api/ccdiProject'
|
||||
```
|
||||
|
||||
**新增方法：**
|
||||
|
||||
```javascript
|
||||
/** 获取状态统计 */
|
||||
getStatusCounts() {
|
||||
return getProjectStatusCounts().then(response => {
|
||||
this.tabCounts = response.data
|
||||
}).catch(() => {
|
||||
// 统计接口失败时使用默认值，不影响列表显示
|
||||
this.tabCounts = {
|
||||
all: 0,
|
||||
'0': 0,
|
||||
'1': 0,
|
||||
'2': 0
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**修改 created 生命周期：**
|
||||
|
||||
```javascript
|
||||
created() {
|
||||
// 并发加载统计和列表
|
||||
Promise.all([
|
||||
this.getStatusCounts(),
|
||||
this.getList()
|
||||
])
|
||||
}
|
||||
```
|
||||
|
||||
**优化 calculateTabCounts 方法：**
|
||||
|
||||
```javascript
|
||||
/** 计算标签页数量 - 改为从统计接口获取 */
|
||||
calculateTabCounts() {
|
||||
// 方法保留但不执行计算逻辑
|
||||
// 统计数据已从接口获取，直接使用 this.tabCounts
|
||||
}
|
||||
```
|
||||
|
||||
**修改状态变更处理：**
|
||||
|
||||
```javascript
|
||||
/** 确认归档 */
|
||||
handleConfirmArchive(data) {
|
||||
console.log('确认归档:', data)
|
||||
this.$modal.msgSuccess('项目已归档')
|
||||
this.archiveDialogVisible = false
|
||||
// 同时刷新统计和列表
|
||||
Promise.all([
|
||||
this.getStatusCounts(),
|
||||
this.getList()
|
||||
])
|
||||
}
|
||||
|
||||
/** 提交项目表单 */
|
||||
handleSubmitProject(data) {
|
||||
this.addDialogVisible = false
|
||||
// 同时刷新统计和列表
|
||||
Promise.all([
|
||||
this.getStatusCounts(),
|
||||
this.getList()
|
||||
])
|
||||
}
|
||||
```
|
||||
|
||||
**优化 getList 方法：**
|
||||
|
||||
```javascript
|
||||
/** 查询项目列表 */
|
||||
getList() {
|
||||
this.loading = true
|
||||
listProject(this.queryParams).then(response => {
|
||||
this.projectList = response.rows
|
||||
this.total = response.total
|
||||
this.loading = false
|
||||
// 不再需要调用 calculateTabCounts
|
||||
}).catch(() => {
|
||||
this.loading = false
|
||||
this.$modal.msgError('加载项目列表失败')
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、数据流设计
|
||||
|
||||
### 5.1 数据加载时机
|
||||
|
||||
| 场景 | 刷新统计 | 刷新列表 | 说明 |
|
||||
|------|---------|---------|------|
|
||||
| 页面首次加载 | ✓ | ✓ | 并发请求 |
|
||||
| 标签页切换 | - | ✓ | 仅列表变化 |
|
||||
| 搜索触发 | - | ✓ | 仅列表变化 |
|
||||
| 项目归档 | ✓ | ✓ | 状态变化 |
|
||||
| 新建项目 | ✓ | ✓ | 总数增加 |
|
||||
| 删除项目 | ✓ | ✓ | 总数减少 |
|
||||
| 重新分析 | - | ✓ | 状态不变 |
|
||||
|
||||
### 5.2 并发加载优化
|
||||
|
||||
```javascript
|
||||
// 使用 Promise.all 并发请求，提升加载速度
|
||||
Promise.all([
|
||||
this.getStatusCounts(), // 统计接口
|
||||
this.getList() // 列表接口
|
||||
])
|
||||
```
|
||||
|
||||
### 5.3 错误处理策略
|
||||
|
||||
**统计接口失败：**
|
||||
- 不阻塞页面加载
|
||||
- 标签页显示 0，但列表正常显示
|
||||
- 控制台记录错误日志
|
||||
|
||||
**列表接口失败：**
|
||||
- 显示错误提示
|
||||
- 保持现有数据不变
|
||||
- Loading 状态正常关闭
|
||||
|
||||
---
|
||||
|
||||
## 六、性能考虑
|
||||
|
||||
### 6.1 接口性能
|
||||
|
||||
**统计接口：**
|
||||
- 使用 COUNT + GROUP BY，无需查询详细字段
|
||||
- 数据量极小（仅4个数字）
|
||||
- 执行速度快，可在 100ms 内完成
|
||||
|
||||
**列表接口：**
|
||||
- 保持现有分页逻辑
|
||||
- 不受统计接口影响
|
||||
|
||||
### 6.2 前端性能
|
||||
|
||||
**并发请求：**
|
||||
- 统计和列表同时发起，不串行等待
|
||||
- 总耗时 = max(统计耗时, 列表耗时)
|
||||
|
||||
**缓存策略：**
|
||||
- 统计数据在前端内存中保留
|
||||
- 仅在状态变更时重新获取
|
||||
|
||||
---
|
||||
|
||||
## 七、测试要点
|
||||
|
||||
### 7.1 后端测试
|
||||
|
||||
**单元测试：**
|
||||
- 测试统计接口返回数据格式
|
||||
- 测试空数据情况（无项目时）
|
||||
- 测试各状态的数据准确性
|
||||
|
||||
**集成测试：**
|
||||
- 使用 Swagger 测试接口响应
|
||||
- 验证权限控制
|
||||
|
||||
### 7.2 前端测试
|
||||
|
||||
**功能测试：**
|
||||
- 搜索按钮点击触发搜索
|
||||
- 回车键触发搜索
|
||||
- 清空输入框触发搜索
|
||||
- 标签页显示正确的统计数据
|
||||
- 状态标签显示正确的颜色和文字
|
||||
|
||||
**UI 测试：**
|
||||
- 搜索按钮样式与输入框融合
|
||||
- 状态标签小圆点样式正确
|
||||
- 不同状态的颜色区分明显
|
||||
|
||||
**错误场景测试：**
|
||||
- 统计接口失败时页面正常显示
|
||||
- 列表接口失败时错误提示正确
|
||||
- 网络异常时的降级处理
|
||||
|
||||
---
|
||||
|
||||
## 八、改动文件清单
|
||||
|
||||
### 8.1 后端文件
|
||||
|
||||
1. `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectController.java`
|
||||
- 新增统计接口方法
|
||||
|
||||
2. `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectService.java`
|
||||
- 新增服务方法定义
|
||||
|
||||
3. `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java`
|
||||
- 实现统计逻辑
|
||||
|
||||
### 8.2 前端文件
|
||||
|
||||
1. `ruoyi-ui/src/api/ccdiProject.js`
|
||||
- 新增统计接口调用
|
||||
|
||||
2. `ruoyi-ui/src/views/ccdiProject/components/SearchBar.vue`
|
||||
- 添加内嵌搜索按钮
|
||||
- 调整输入框宽度
|
||||
|
||||
3. `ruoyi-ui/src/views/ccdiProject/components/ProjectTable.vue`
|
||||
- 改造状态标签样式
|
||||
- 新增 getStatusText 方法
|
||||
- 删除 getStatusType 方法
|
||||
|
||||
4. `ruoyi-ui/src/views/ccdiProject/index.vue`
|
||||
- 引入统计接口
|
||||
- 修改 created 生命周期
|
||||
- 新增 getStatusCounts 方法
|
||||
- 优化状态变更处理
|
||||
|
||||
---
|
||||
|
||||
## 九、实施计划
|
||||
|
||||
### 9.1 实施顺序
|
||||
|
||||
1. **后端开发**（优先）
|
||||
- 实现统计接口
|
||||
- Swagger 测试验证
|
||||
|
||||
2. **前端开发**
|
||||
- API 接口定义
|
||||
- SearchBar 组件改造
|
||||
- ProjectTable 组件改造
|
||||
- 主页面集成
|
||||
|
||||
3. **联调测试**
|
||||
- 前后端联调
|
||||
- 功能测试
|
||||
- UI 测试
|
||||
|
||||
### 9.2 预估工时
|
||||
|
||||
- 后端开发：1 小时
|
||||
- 前端开发：2 小时
|
||||
- 联调测试：1 小时
|
||||
- **总计：4 小时**
|
||||
|
||||
---
|
||||
|
||||
## 十、风险评估
|
||||
|
||||
### 10.1 技术风险
|
||||
|
||||
**风险：** 统计接口性能问题
|
||||
**影响：** 中
|
||||
**缓解措施：**
|
||||
- 使用 COUNT + GROUP BY 优化查询
|
||||
- 添加数据库索引（status 字段）
|
||||
- 监控接口响应时间
|
||||
|
||||
**风险：** 前端样式兼容性
|
||||
**影响：** 低
|
||||
**缓解措施：**
|
||||
- 使用标准的 CSS 属性
|
||||
- 测试主流浏览器
|
||||
|
||||
### 10.2 业务风险
|
||||
|
||||
**风险：** 统计数据与实际不符
|
||||
**影响：** 高
|
||||
**缓解措施：**
|
||||
- 使用数据库事务保证一致性
|
||||
- 状态变更时立即刷新统计
|
||||
- 添加数据校验
|
||||
|
||||
---
|
||||
|
||||
## 十一、后续优化
|
||||
|
||||
### 11.1 短期优化
|
||||
|
||||
- 添加统计数据的本地缓存（5秒过期）
|
||||
- 优化错误提示文案
|
||||
|
||||
### 11.2 长期优化
|
||||
|
||||
- 支持按时间范围统计
|
||||
- 添加趋势图表
|
||||
- 支持自定义状态
|
||||
|
||||
---
|
||||
|
||||
**设计完成日期：** 2026-02-27
|
||||
**预计实施日期：** 待定
|
||||
Reference in New Issue
Block a user