wkc/ccdi

Fork 0

Files

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

2026-02-27 17:19:58 +08:00

16 KiB

Raw Blame History

项目管理标签页状态统计修复设计文档

文档信息

创建日期: 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):

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

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):

/**
 * 查询各状态的项目总数（不受搜索条件影响）
 * @return 状态统计
 */
CcdiProjectStatusCountsVO getStatusCounts();

实现类 (CcdiProjectServiceImpl.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）

优化方案（可选）:

如果性能要求高，可以改为单次查询：

@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 方法:

List<Map<String, Object>> countGroupByStatus();

XML SQL:

<select id="countGroupByStatus" resultType="map">
    SELECT
        status,
        COUNT(*) as count
    FROM ccdi_project
    GROUP BY status
</select>

3. Controller 层

文件: CcdiProjectController.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

// 查询项目状态统计
export function getStatusCounts() {
  return request({
    url: '/ccdi/project/statusCounts',
    method: 'get'
  })
}

2. 页面组件改造

文件: ruoyi-ui/src/views/ccdiProject/index.vue

修改点 1: 导入新 API

import { listProject, getStatusCounts } from '@/api/ccdiProject'

修改点 2: 重构 getList() 方法

/** 查询项目列表 */
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. 单元测试

测试文件: CcdiProjectServiceTest.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 测试:

访问: http://localhost:8080/swagger-ui/index.html
找到: 纪检初核项目管理 → GET /ccdi/project/statusCounts
点击 "Try it out" → "Execute"

预期响应:

{
  "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. 页面加载测试

步骤:

打开项目管理页面
观察标签页数字

预期结果:

标签页显示正确的总数（例如：全部项目(100)）
数字不随分页变化

2. 搜索测试

步骤:

在搜索框输入项目名称
点击搜索

预期结果:

列表正确过滤
标签页数字保持不变（显示总数）

3. 分页测试

步骤:

切换到第 2 页

预期结果:

列表切换到第 2 页
标签页数字保持不变

4. 状态切换测试

步骤:

点击"进行中"标签

预期结果:

列表只显示进行中的项目
标签页数字保持不变（仍显示总数）

5. 网络错误测试

步骤:

模拟统计接口失败

预期结果:

列表正常显示
标签页显示 0 或保持上次数据
不阻塞用户操作

集成测试

端到端测试流程:

准备数据: 在数据库中插入测试项目
- 10 个进行中项目
- 15 个已完成项目
- 5 个已归档项目

执行测试:

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)

预期结果: 所有验证点通过

性能考虑

后端性能

统计查询优化:

使用 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 分钟)

创建 VO 类 (5 分钟)
- 新建 CcdiProjectStatusCountsVO.java
- 添加字段和 Lombok 注解
Service 层开发 (15 分钟)
- 接口添加方法声明
- 实现类编写统计逻辑
- (可选) Mapper 添加 GROUP BY 查询
Controller 层开发 (5 分钟)
- 添加 /statusCounts 接口
- 添加 Swagger 注释
本地测试 (5 分钟)
- 启动项目
- 使用 Swagger 测试接口

前端开发 (20 分钟)

API 层修改 (5 分钟)
- 添加 getStatusCounts() 函数
页面组件修改 (10 分钟)
- 导入新 API
- 修改 getList() 方法
- 删除 calculateTabCounts() 方法
本地测试 (5 分钟)
- 启动前端
- 验证功能

测试验证 (15 分钟)

后端接口测试 (5 分钟)
- Swagger 测试各场景
前端功能测试 (10 分钟)
- 执行测试方案中的所有用例

总计时间: 65 分钟

验收标准

功能验收

后端 /statusCounts 接口返回正确的统计数字
前端标签页显示数据库中的完整统计
搜索不影响标签页统计数字
分页不影响标签页统计数字
状态过滤不影响标签页统计数字

性能验收

统计接口响应时间 < 100ms
页面加载时间无明显增加

代码质量

后端代码符合项目规范
前端代码符合项目规范
添加必要的注释和文档

后续优化

短期优化 (可选)

错误处理增强
- 前端对统计接口失败进行友好提示
- 后端添加异常捕获和日志
性能优化
- 使用单次 GROUP BY 查询替代多次 COUNT
- 为 status 字段添加索引

长期优化 (可选)

缓存机制
- 使用 Redis 缓存统计结果
- 设置 5 分钟过期时间
- 项目变更时清除缓存
实时更新
- 使用 WebSocket 推送统计更新
- 减少轮询请求

附录

参考资料

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

16 KiB Raw Blame History Unescape Escape

项目管理标签页状态统计修复设计文档

文档信息

问题背景

当前问题

代码位置

当前实现分析

需求说明

功能需求

设计方案

整体架构

后端设计

1. 新增 VO 类

2. Service 层

3. Controller 层

前端设计

1. API 层

2. 页面组件改造

数据流设计

测试方案

后端测试

1. 单元测试

2. 接口测试

前端测试

1. 页面加载测试

2. 搜索测试

3. 分页测试

4. 状态切换测试

5. 网络错误测试

集成测试

性能考虑

后端性能

前端性能

风险与应对

风险 1: 统计数据不一致

风险 2: 统计接口失败

风险 3: 大数据量性能

实施计划

后端开发 (30 分钟)

前端开发 (20 分钟)

测试验证 (15 分钟)

总计时间: 65 分钟

验收标准

功能验收

性能验收

代码质量

后续优化

短期优化 (可选)

长期优化 (可选)

附录

相关文件清单

参考资料

16 KiB

Raw Blame History