ccdi/docs/plans/2026-02-27-project-management-improvements-design.md

# 项目管理页面改进设计文档

**日期：** 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
**预计实施日期：** 待定