ccdi/docs/design/2026-03-29-project-detail-risk-overview-risk-people-pagination-design.md

项目详情风险总览员工列表分页设计文档

模块: 项目详情 - 结果总览 - 风险总览员工列表 日期: 2026-03-29

一、背景

当前项目详情页 结果总览 -> 风险总览 中的员工列表直接消费 GET /ccdi/project/overview/risk-people 返回的全量 overviewList。页面没有分页能力，项目内风险员工较多时会导致：

1. 单屏信息过长，浏览成本高。
2. 前端一次性渲染全量列表，交互体验不稳定。
3. 接口返回风格与当前结果总览域内其他分页接口不一致。

本轮需求要求为该员工列表增加分页，并固定为每页 5 条。同时，需求明确要求改造现有接口，不采用前端本地切片或新增补丁接口的方式。

二、目标

本次设计目标如下：

1. 将 GET /ccdi/project/overview/risk-people 改造成真实分页接口。
2. 风险总览员工列表固定每页展示 5 条。
3. 前端翻页时仅刷新员工列表，不影响结果总览内其他区块。
4. 分页接口返回结构对齐项目现有分页风格，统一为 rows + total + pageNum + pageSize。

三、范围

3.1 本次范围

• 改造 risk-people 接口入参与返回结构
• 为后端风险人员查询增加数据库分页
• 调整项目详情结果总览首屏数据装配
• 在 RiskPeopleSection.vue 增加分页条与翻页请求
• 补充本次设计文档、设计记录，以及后续前后端实施计划入口

3.2 不在本次范围

• 不修改风险仪表盘接口
• 不修改风险模型卡片与模型命中人员查询
• 不修改风险明细区块
• 不新增筛选条件、搜索条件或排序条件
• 不修改风险等级、命中模型数、核心异常点的业务口径
• 不删除现有 GET /ccdi/project/overview/top-risk-people

四、现状分析

4.1 前端现状

当前 PreliminaryCheck.vue 在页面加载时并发请求：

• GET /ccdi/project/overview/dashboard
• GET /ccdi/project/overview/risk-people
• GET /ccdi/project/overview/risk-models/cards
• GET /ccdi/project/overview/suspicious-transactions
• GET /ccdi/project/overview/employee-credit-negative

其中 risk-people 的返回结果被直接注入 currentData.riskPeople.overviewList，RiskPeopleSection.vue 直接用该数组渲染表格，没有分页状态，也没有独立二次加载链路。

4.2 后端现状

当前 CcdiProjectOverviewController.getRiskPeople(Long projectId) 只接收项目 ID。

CcdiProjectOverviewServiceImpl.getRiskPeopleOverview(Long projectId) 的实现为：

1. 校验项目存在
2. 调用 overviewMapper.selectRiskPeopleOverviewByProjectId(projectId) 查询全量员工结果
3. 在 Java 层逐行映射为 overviewList
4. 返回 CcdiProjectRiskPeopleOverviewVO { overviewList }

当前 SQL 直接从 ccdi_project_overview_employee_result 查询并排序：

• risk_level_sort asc
• model_count desc
• rule_count desc
• staff_id_card asc

现状能够提供正确列表语义，但不具备分页能力。

五、方案对比

5.1 方案 A：改造现有 risk-people 为标准分页接口

做法：

• 保持接口路径不变
• 入参扩展为 projectId + pageNum + pageSize
• 返回结构改为 rows + total + pageNum + pageSize
• 后端通过数据库分页查询返回当前页数据
• 前端首屏与翻页统一走该接口

优点：

• 满足“改接口”的明确要求
• 与 risk-models/people、employee-credit-negative 的分页风格一致
• 逻辑单一，没有重复接口
• 数据量增大时性能与语义都正确

缺点：

• 需要同步调整前后端契约与测试

5.2 方案 B：新增 risk-people/page，保留原接口不动

做法：

• 原 risk-people 继续返回全量列表
• 新增单独分页接口供前端切换

问题：

• 留下两个语义重复的接口
• 不符合“改接口”的要求
• 增加后续维护成本

5.3 方案 C：后端仍全量查，Java 或前端再切页

做法：

• 接口表面返回分页结构
• 实际仍走全量查询后截断

问题：

• 不是真分页
• 数据量增大时性能与语义都不成立
• 属于补丁式方案，不符合最短路径要求

5.4 结论

采用方案 A。

六、接口设计

6.1 接口路径

• GET /ccdi/project/overview/risk-people

6.2 入参

• projectId: 项目 ID，必填
• pageNum: 页码，非必填，默认 1
• pageSize: 每页条数，非必填，默认 5

说明：

• 前端固定传 pageSize = 5
• 后端默认值同样收敛为 5，避免前端漏传时行为偏移

6.3 返回结构

返回结构统一为：

{
  "rows": [
    {
      "name": "李四",
      "idNo": "330000000000000001",
      "department": "信息二部",
      "riskCount": 5,
      "riskLevel": "中风险",
      "riskLevelType": "warning",
      "modelCount": 4,
      "riskPoint": "大额单笔收入、疑似兼职",
      "actionLabel": "查看项目"
    }
  ],
  "total": 18,
  "pageNum": 1,
  "pageSize": 5
}

说明：

• 原 overviewList 字段移除，统一改为 rows
• 单行字段保持现有页面绑定语义不变
• 本次不引入额外统计字段

七、后端设计

7.1 控制器

CcdiProjectOverviewController.getRiskPeople 改为接收独立 DTO，例如：

• CcdiProjectRiskPeopleQueryDTO

DTO 仅包含：

• projectId
• pageNum
• pageSize

不额外引入筛选项，保持最短路径。

7.2 服务层

ICcdiProjectOverviewService.getRiskPeopleOverview 改为接收查询 DTO，并返回分页 VO。

服务层职责：

1. 校验项目存在
2. 规范化分页参数，默认 pageNum=1、pageSize=5
3. 构造 MyBatis Plus Page
4. 调用 mapper 分页查询
5. 将记录映射为现有员工列表行结构
6. 返回 rows + total + pageNum + pageSize

7.3 VO 调整

CcdiProjectRiskPeopleOverviewVO 改为标准分页 VO，字段包括：

• List<CcdiProjectRiskPeopleOverviewItemVO> rows
• Long total
• Long pageNum
• Long pageSize

说明：

• CcdiProjectRiskPeopleOverviewItemVO 本身字段不做语义调整
• 既有的风险等级映射与异常点标签来源保持不变

7.4 Mapper 与 SQL

Mapper 从“全量列表查询”改为“分页查询”，直接在数据库层完成分页。

排序规则保持现状不变：

• risk_level_sort asc
• model_count desc
• rule_count desc
• staff_id_card asc

数据来源继续使用 ccdi_project_overview_employee_result，不新增统计口径，不回退到历史复杂聚合链路。

7.5 默认值与边界

• projectId 为空时沿用现有参数校验/项目不存在校验逻辑
• pageNum <= 0 时按 1 处理
• pageSize <= 0 或为空时按 5 处理
• 本次不开放前端修改每页条数，接口虽接收 pageSize，但页面固定使用 5

八、前端设计

8.1 API 封装

ruoyi-ui/src/api/ccdi/projectOverview.js 中：

• getOverviewRiskPeople 从接收单个 projectId 改为接收 params
• 透传：
  • projectId
  • pageNum
  • pageSize

8.2 首屏加载

PreliminaryCheck.vue 首次加载结果总览时，请求：

• getOverviewRiskPeople({ projectId, pageNum: 1, pageSize: 5 })

返回结果注入 currentData.riskPeople 时，直接保存分页结构：

• rows
• total
• pageNum
• pageSize

页面是否进入 loaded 状态的判断，从原来的 overviewList.length 改为 rows.length。

8.3 风险总览员工列表组件

RiskPeopleSection.vue 调整为：

1. 表格数据源从 sectionData.overviewList 改为 sectionData.rows
2. 在表格下方增加分页组件
3. 分页组件固定：
   • :page-sizes="[5]"
   • layout="total, prev, pager, next, jumper"
4. 页码变化时触发独立请求，仅刷新员工列表分页数据

分页条展示规则：

• total > 0 时展示
• total = 0 时隐藏

8.4 页面刷新策略

翻页时只刷新风险总览员工列表，不重新拉取：

• 风险仪表盘
• 风险模型卡片
• 风险明细涉疑交易
• 风险明细员工负面征信

这样可以避免其他区块闪动，也避免把简单翻页放大成整页重载。

8.5 交互保持不变

以下内容本次保持不变：

• 表格列顺序
• 风险等级标签渲染
• 核心异常点标签拆分与色板逻辑
• 操作列文案与点击事件
• 空态文案

九、测试设计

9.1 后端测试

新增或调整以下验证：

1. Controller 测试

   • 断言 /risk-people 接口改为接收 DTO
   • 断言返回 rows + total + pageNum + pageSize

2. Service 测试

   • 断言服务层使用分页参数构造 Page
   • 断言现有字段映射未变化
   • 断言默认分页参数回落为 1 / 5

3. Mapper/SQL 测试

   • 断言风险人员查询改为分页查询方法
   • 断言排序字段未变化
   • 断言数据来源仍为 ccdi_project_overview_employee_result

9.2 前端测试

新增或调整以下验证：

1. API 封装测试

   • 断言 getOverviewRiskPeople(params) 透传 projectId/pageNum/pageSize

2. 页面接入测试

   • 断言 PreliminaryCheck.vue 首次加载传 pageNum: 1
   • 断言固定传 pageSize: 5
   • 断言风险人员数据改为读取 rows

3. 风险总览组件测试

   • 断言 RiskPeopleSection.vue 存在分页组件
   • 断言分页绑定 rows/total/pageNum/pageSize
   • 断言分页大小固定为 5

十、实施文档要求

本次设计确认后，按仓库规范继续产出两份实施计划：

• 后端实施计划：docs/plans/backend/
• 前端实施计划：docs/plans/frontend/

实施完成后，补充对应实施记录，记录本次真实改动内容。

十一、结论

本次需求本质是将结果总览中的风险员工列表从“全量列表展示”升级为“标准分页列表展示”。

最终方案为：

1. 保持 GET /ccdi/project/overview/risk-people 路径不变
2. 改为标准分页接口，返回 rows + total + pageNum + pageSize
3. 后端在数据库层做真分页，默认每页 5 条
4. 前端首屏和翻页统一走该接口
5. 翻页仅刷新员工列表，不重载结果总览其他区块

该方案满足需求边界明确、链路完整、实现路径最短，且不引入额外补丁接口或兼容分支。