docs: 添加项目状态统计修复设计文档

2026-02-27 17:19:58 +08:00
parent 117ab924d5
commit e532d4d915
1 changed files with 635 additions and 0 deletions
--- a/docs/plans/2026-02-27-project-status-counts-fix-design.md
+++ b/docs/plans/2026-02-27-project-status-counts-fix-design.md
@@ -0,0 +1,635 @@
+# 项目管理标签页状态统计修复设计文档
+
+## 文档信息
+
+- **创建日期**: 2026-02-27
+- **作者**: Claude Code
+- **状态**: 待实施
+
+## 问题背景
+
+### 当前问题
+
+项目管理页面的标签页筛选功能中，各状态的项目计数不正确。具体表现为：
+
+- **现象**: 标签页显示的数量远小于实际总数
+- **根本原因**: 前端只统计当前页的数据来计算各状态的数量
+- **影响**: 用户无法了解各状态的完整项目分布情况
+
+### 代码位置
+
+**前端代码**:
+- 页面组件: `ruoyi-ui/src/views/ccdiProject/index.vue`
+- API 定义: `ruoyi-ui/src/api/ccdiProject.js`
+
+**后端代码**:
+- Controller: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectController.java`
+- Service 接口: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectService.java`
+- Service 实现: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java`
+
+### 当前实现分析
+
+**问题代码** (index.vue:136-145):
+
+```javascript
+calculateTabCounts() {
+  // 注意：这里需要后端API返回所有状态的数量统计
+  // 目前暂时使用当前页的数据进行计算
+  this.tabCounts = {
+    all: this.total,
+    '0': this.projectList.filter(p => p.status === '0').length,
+    '1': this.projectList.filter(p => p.status === '1').length,
+    '2': this.projectList.filter(p => p.status === '2').length
+  }
+}
+```
+
+**问题分析**:
+- `projectList` 只包含当前页的数据（默认10条）
+- 过滤计算只能得到当前页中各状态的数量
+- 用户看到的是"当前页有5个进行中的项目"，而非"总共有30个进行中的项目"
+
+## 需求说明
+
+### 功能需求
+
+**预期行为**:
+- 标签页应显示数据库中所有该状态的项目总数
+- 状态统计不受搜索条件和分页影响
+- 状态统计随列表一起刷新
+
+**非功能性需求**:
+- 性能: 统计查询应快速响应（< 100ms）
+- 准确性: 统计数字必须与数据库一致
+- 实时性: 每次刷新列表时同步更新统计
+
+## 设计方案
+
+### 整体架构
+
+采用**独立统计接口**方案：
+- 后端新增 `/ccdi/project/statusCounts` 接口
+- 前端在加载列表时并行调用统计接口
+- 两个请求独立，数据互不影响
+
+### 后端设计
+
+#### 1. 新增 VO 类
+
+**文件**: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectStatusCountsVO.java`
+
+```java
+package com.ruoyi.ccdi.project.domain.vo;
+
+import lombok.Data;
+
+/**
+ * 项目状态统计VO
+ */
+@Data
+public class CcdiProjectStatusCountsVO {
+    /** 全部项目总数 */
+    private Long all;
+    /** 进行中项目数（状态0） */
+    private Long status0;
+    /** 已完成项目数（状态1） */
+    private Long status1;
+    /** 已归档项目数（状态2） */
+    private Long status2;
+}
+```
+
+**设计说明**:
+- 使用 `Long` 类型支持大数据量
+- 字段命名清晰，便于前端使用
+- 不包含搜索条件，始终统计全量数据
+
+#### 2. Service 层
+
+**接口定义** (`ICcdiProjectService.java`):
+
+```java
+/**
+ * 查询各状态的项目总数（不受搜索条件影响）
+ * @return 状态统计
+ */
+CcdiProjectStatusCountsVO getStatusCounts();
+```
+
+**实现类** (`CcdiProjectServiceImpl.java`):
+
+```java
+@Override
+public CcdiProjectStatusCountsVO getStatusCounts() {
+    CcdiProjectStatusCountsVO vo = new CcdiProjectStatusCountsVO();
+
+    // 统计全部项目
+    vo.setAll(ccdiProjectMapper.selectCount(null));
+
+    // 统计各状态项目
+    vo.setStatus0(ccdiProjectMapper.selectCount(
+        new LambdaQueryWrapper<CcdiProject>()
+            .eq(CcdiProject::getStatus, "0")
+    ));
+    vo.setStatus1(ccdiProjectMapper.selectCount(
+        new LambdaQueryWrapper<CcdiProject>()
+            .eq(CcdiProject::getStatus, "1")
+    ));
+    vo.setStatus2(ccdiProjectMapper.selectCount(
+        new LambdaQueryWrapper<CcdiProject>()
+            .eq(CcdiProject::getStatus, "2")
+    ));
+
+    return vo;
+}
+```
+
+**实现要点**:
+- 使用 MyBatis Plus 的 `selectCount` 方法
+- 不添加任何过滤条件
+- 可以优化为一次查询返回所有统计（使用 GROUP BY）
+
+**优化方案**（可选）:
+
+如果性能要求高，可以改为单次查询：
+
+```java
+@Override
+public CcdiProjectStatusCountsVO getStatusCounts() {
+    // 查询各状态的统计
+    List<Map<String, Object>> counts = ccdiProjectMapper.countGroupByStatus();
+
+    CcdiProjectStatusCountsVO vo = new CcdiProjectStatusCountsVO();
+    vo.setAll(0L);
+    vo.setStatus0(0L);
+    vo.setStatus1(0L);
+    vo.setStatus2(0L);
+
+    for (Map<String, Object> item : counts) {
+        String status = (String) item.get("status");
+        Long count = (Long) item.get("count");
+
+        vo.setAll(vo.getAll() + count);
+        if ("0".equals(status)) {
+            vo.setStatus0(count);
+        } else if ("1".equals(status)) {
+            vo.setStatus1(count);
+        } else if ("2".equals(status)) {
+            vo.setStatus2(count);
+        }
+    }
+
+    return vo;
+}
+```
+
+Mapper 方法:
+
+```java
+List<Map<String, Object>> countGroupByStatus();
+```
+
+XML SQL:
+
+```xml
+<select id="countGroupByStatus" resultType="map">
+    SELECT
+        status,
+        COUNT(*) as count
+    FROM ccdi_project
+    GROUP BY status
+</select>
+```
+
+#### 3. Controller 层
+
+**文件**: `CcdiProjectController.java`
+
+```java
+/**
+ * 查询项目状态统计
+ */
+@GetMapping("/statusCounts")
+@Operation(summary = "查询项目状态统计")
+@PreAuthorize("@ss.hasPermi('ccdi:project:list')")
+public AjaxResult getStatusCounts() {
+    CcdiProjectStatusCountsVO counts = projectService.getStatusCounts();
+    return AjaxResult.success(counts);
+}
+```
+
+**设计说明**:
+- 不接收任何查询参数
+- 使用与列表接口相同的权限注解
+- 返回标准的 AjaxResult 格式
+
+### 前端设计
+
+#### 1. API 层
+
+**文件**: `ruoyi-ui/src/api/ccdiProject.js`
+
+```javascript
+// 查询项目状态统计
+export function getStatusCounts() {
+  return request({
+    url: '/ccdi/project/statusCounts',
+    method: 'get'
+  })
+}
+```
+
+#### 2. 页面组件改造
+
+**文件**: `ruoyi-ui/src/views/ccdiProject/index.vue`
+
+**修改点 1**: 导入新 API
+
+```javascript
+import { listProject, getStatusCounts } from '@/api/ccdiProject'
+```
+
+**修改点 2**: 重构 `getList()` 方法
+
+```javascript
+/** 查询项目列表 */
+getList() {
+  this.loading = true
+
+  // 并行请求列表数据和状态统计
+  Promise.all([
+    listProject(this.queryParams),
+    getStatusCounts()
+  ]).then(([listResponse, countsResponse]) => {
+    // 处理列表数据
+    this.projectList = listResponse.rows
+    this.total = listResponse.total
+
+    // 处理状态统计
+    const counts = countsResponse.data
+    this.tabCounts = {
+      all: counts.all,
+      '0': counts.status0,
+      '1': counts.status1,
+      '2': counts.status2
+    }
+
+    this.loading = false
+  }).catch(() => {
+    this.loading = false
+  })
+}
+```
+
+**修改点 3**: 删除旧方法
+
+删除 `calculateTabCounts()` 方法及其调用（第 136-145 行）。
+
+**设计说明**:
+- 使用 `Promise.all` 并行请求，提高性能
+- 两个请求独立失败互不影响（可以优化错误处理）
+- 状态统计使用后端返回的准确数据
+
+### 数据流设计
+
+```
+用户操作（打开页面/搜索/切换标签/翻页）
+    ↓
+前端调用 getList() 方法
+    ↓
+并行发送两个请求:
+  ┌─────────────────────────┬────────────────────────┐
+  │ listProject(queryParams)│ getStatusCounts()      │
+  │ - 带搜索条件             │ - 无参数               │
+  │ - 带分页参数             │ - 返回全量统计         │
+  │ - 返回当前页数据         │                        │
+  └─────────────────────────┴────────────────────────┘
+    ↓                           ↓
+后端处理                       后端处理
+- 根据条件过滤                 - COUNT 查询全部
+- 分页返回结果                 - 按 status 分组统计
+    ↓                           ↓
+前端接收响应 ←─────────────────┘
+    ↓
+更新状态:
+- projectList: 列表数据（受搜索/分页影响）
+- total: 当前筛选条件的总数
+- tabCounts: 各状态的完整统计（不受搜索影响）
+    ↓
+页面渲染:
+- 表格: 显示当前页项目
+- 标签: 显示固定统计数字
+```
+
+**关键特性**:
+1. **并行请求**: 两个请求同时发出，不阻塞
+2. **数据独立**: 列表数据和统计数据来源不同
+3. **统计固定**: 标签页数字不随搜索/分页变化
+4. **列表过滤**: 表格内容根据搜索条件正确过滤
+
+## 测试方案
+
+### 后端测试
+
+#### 1. 单元测试
+
+**测试文件**: `CcdiProjectServiceTest.java`
+
+```java
+@Test
+void testGetStatusCounts() {
+    // 准备测试数据
+    // 创建 3 个进行中项目
+    // 创建 2 个已完成项目
+    // 创建 1 个已归档项目
+
+    // 执行测试
+    CcdiProjectStatusCountsVO result = projectService.getStatusCounts();
+
+    // 验证结果
+    assertEquals(6L, result.getAll());
+    assertEquals(3L, result.getStatus0());
+    assertEquals(2L, result.getStatus1());
+    assertEquals(1L, result.getStatus2());
+}
+```
+
+#### 2. 接口测试
+
+**使用 Swagger UI 测试**:
+
+1. 访问: `http://localhost:8080/swagger-ui/index.html`
+2. 找到: 纪检初核项目管理 → GET /ccdi/project/statusCounts
+3. 点击 "Try it out" → "Execute"
+
+**预期响应**:
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "all": 100,
+    "status0": 30,
+    "status1": 50,
+    "status2": 20
+  }
+}
+```
+
+**测试用例**:
+
+| 用例编号 | 场景 | 预期结果 |
+|---------|------|---------|
+| TC01 | 数据库无项目 | all=0, status0=0, status1=0, status2=0 |
+| TC02 | 只有进行中项目 | all=N, status0=N, status1=0, status2=0 |
+| TC03 | 混合状态项目 | 各状态数字之和等于 all |
+| TC04 | 大数据量（1000+） | 查询时间 < 100ms |
+
+### 前端测试
+
+#### 1. 页面加载测试
+
+**步骤**:
+1. 打开项目管理页面
+2. 观察标签页数字
+
+**预期结果**:
+- 标签页显示正确的总数（例如：全部项目(100)）
+- 数字不随分页变化
+
+#### 2. 搜索测试
+
+**步骤**:
+1. 在搜索框输入项目名称
+2. 点击搜索
+
+**预期结果**:
+- 列表正确过滤
+- 标签页数字保持不变（显示总数）
+
+#### 3. 分页测试
+
+**步骤**:
+1. 切换到第 2 页
+
+**预期结果**:
+- 列表切换到第 2 页
+- 标签页数字保持不变
+
+#### 4. 状态切换测试
+
+**步骤**:
+1. 点击"进行中"标签
+
+**预期结果**:
+- 列表只显示进行中的项目
+- 标签页数字保持不变（仍显示总数）
+
+#### 5. 网络错误测试
+
+**步骤**:
+1. 模拟统计接口失败
+
+**预期结果**:
+- 列表正常显示
+- 标签页显示 0 或保持上次数据
+- 不阻塞用户操作
+
+### 集成测试
+
+**端到端测试流程**:
+
+1. **准备数据**: 在数据库中插入测试项目
+   - 10 个进行中项目
+   - 15 个已完成项目
+   - 5 个已归档项目
+
+2. **执行测试**:
+   ```
+   a. 打开项目管理页面
+   b. 验证标签显示: 全部(30), 进行中(10), 已完成(15), 已归档(5)
+   c. 搜索项目名称（匹配 5 个）
+   d. 验证列表显示 5 个项目
+   e. 验证标签仍显示: 全部(30), 进行中(10), 已完成(15), 已归档(5)
+   f. 切换到第 2 页
+   g. 验证列表切换，标签数字不变
+   h. 点击"进行中"标签
+   i. 验证列表只显示进行中项目
+   j. 验证标签仍显示: 全部(30), 进行中(10), 已完成(15), 已归档(5)
+   ```
+
+3. **预期结果**: 所有验证点通过
+
+## 性能考虑
+
+### 后端性能
+
+**统计查询优化**:
+- 使用 `COUNT(*)` 查询，性能较好
+- 考虑为 `status` 字段添加索引（如果项目数量 > 10000）
+- 单次 GROUP BY 查询优于多次 COUNT 查询
+
+**预估性能**:
+- 项目数 < 1000: 响应时间 < 50ms
+- 项目数 1000-10000: 响应时间 50-100ms
+- 项目数 > 10000: 考虑添加缓存或索引
+
+### 前端性能
+
+**并行请求**:
+- `Promise.all` 同时发起两个请求
+- 总等待时间 = max(listTime, countsTime)
+- 不影响用户体验
+
+**请求频率**:
+- 仅在页面加载、搜索、翻页时请求
+- 不会产生过多网络流量
+
+## 风险与应对
+
+### 风险 1: 统计数据不一致
+
+**场景**: 用户在查看页面时，后台数据被其他用户修改
+
+**影响**: 标签页数字与实际不符
+
+**应对方案**:
+- 轻微问题，可接受
+- 用户刷新页面后同步
+- 不需要额外处理
+
+### 风险 2: 统计接口失败
+
+**场景**: 统计接口异常或超时
+
+**影响**: 标签页显示 0 或空白
+
+**应对方案**:
+- 前端增加错误处理
+- 列表接口不受影响
+- 控制台记录错误日志
+
+### 风险 3: 大数据量性能
+
+**场景**: 项目数量超过 10000
+
+**影响**: 统计查询变慢
+
+**应对方案**:
+- 为 status 字段添加索引
+- 使用单次 GROUP BY 查询
+- 考虑添加缓存（Redis）
+
+## 实施计划
+
+### 后端开发 (30 分钟)
+
+1. 创建 VO 类 (5 分钟)
+   - 新建 `CcdiProjectStatusCountsVO.java`
+   - 添加字段和 Lombok 注解
+
+2. Service 层开发 (15 分钟)
+   - 接口添加方法声明
+   - 实现类编写统计逻辑
+   - (可选) Mapper 添加 GROUP BY 查询
+
+3. Controller 层开发 (5 分钟)
+   - 添加 `/statusCounts` 接口
+   - 添加 Swagger 注释
+
+4. 本地测试 (5 分钟)
+   - 启动项目
+   - 使用 Swagger 测试接口
+
+### 前端开发 (20 分钟)
+
+1. API 层修改 (5 分钟)
+   - 添加 `getStatusCounts()` 函数
+
+2. 页面组件修改 (10 分钟)
+   - 导入新 API
+   - 修改 `getList()` 方法
+   - 删除 `calculateTabCounts()` 方法
+
+3. 本地测试 (5 分钟)
+   - 启动前端
+   - 验证功能
+
+### 测试验证 (15 分钟)
+
+1. 后端接口测试 (5 分钟)
+   - Swagger 测试各场景
+
+2. 前端功能测试 (10 分钟)
+   - 执行测试方案中的所有用例
+
+### 总计时间: 65 分钟
+
+## 验收标准
+
+### 功能验收
+
+- [ ] 后端 `/statusCounts` 接口返回正确的统计数字
+- [ ] 前端标签页显示数据库中的完整统计
+- [ ] 搜索不影响标签页统计数字
+- [ ] 分页不影响标签页统计数字
+- [ ] 状态过滤不影响标签页统计数字
+
+### 性能验收
+
+- [ ] 统计接口响应时间 < 100ms
+- [ ] 页面加载时间无明显增加
+
+### 代码质量
+
+- [ ] 后端代码符合项目规范
+- [ ] 前端代码符合项目规范
+- [ ] 添加必要的注释和文档
+
+## 后续优化
+
+### 短期优化 (可选)
+
+1. **错误处理增强**
+   - 前端对统计接口失败进行友好提示
+   - 后端添加异常捕获和日志
+
+2. **性能优化**
+   - 使用单次 GROUP BY 查询替代多次 COUNT
+   - 为 status 字段添加索引
+
+### 长期优化 (可选)
+
+1. **缓存机制**
+   - 使用 Redis 缓存统计结果
+   - 设置 5 分钟过期时间
+   - 项目变更时清除缓存
+
+2. **实时更新**
+   - 使用 WebSocket 推送统计更新
+   - 减少轮询请求
+
+## 附录
+
+### 相关文件清单
+
+**后端新增文件**:
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/vo/CcdiProjectStatusCountsVO.java`
+
+**后端修改文件**:
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/ICcdiProjectService.java`
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectServiceImpl.java`
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectController.java`
+- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiProjectMapper.java` (可选)
+- `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiProjectMapper.xml` (可选)
+
+**前端修改文件**:
+- `ruoyi-ui/src/api/ccdiProject.js`
+- `ruoyi-ui/src/views/ccdiProject/index.vue`
+
+### 参考资料
+
+- MyBatis Plus 官方文档: https://baomidou.com/
+- Element UI 标签页组件: https://element.eleme.cn/#/zh-CN/component/tabs
+- Promise.all 文档: https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise/all