wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

补充风险总览员工列表分页设计文档

Browse Source
This commit is contained in:
wkc
2026-03-29 11:41:49 +08:00
parent 9df1b956b3
commit 865d8f823b
2 changed files with 401 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

364
docs/design/2026-03-29-project-detail-risk-overview-risk-people-pagination-design.md Normal file
View File

@@ -0,0 +1,364 @@
# 项目详情风险总览员工列表分页设计文档
**模块**: 项目详情 - 结果总览 - 风险总览员工列表
**日期**: 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 返回结构
返回结构统一为：
```json
{
"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. 翻页仅刷新员工列表，不重载结果总览其他区块
该方案满足需求边界明确、链路完整、实现路径最短，且不引入额外补丁接口或兼容分支。

37
docs/reports/implementation/2026-03-29-project-detail-risk-overview-risk-people-pagination-design-record.md Normal file
View File

@@ -0,0 +1,37 @@
# 项目详情风险总览员工列表分页设计记录
**日期**: 2026-03-29
## 本次产出
- 新增正式设计文档 `docs/design/2026-03-29-project-detail-risk-overview-risk-people-pagination-design.md`
- 将“风险总览员工列表固定 5 条分页展示”收口为“改造现有 `risk-people` 接口为标准分页接口”方案
## 设计结论
### 后端
- 保持 `GET /ccdi/project/overview/risk-people` 路径不变
- 入参扩展为 `projectId + pageNum + pageSize`
- 返回结构统一为 `rows + total + pageNum + pageSize`
- 基于 `ccdi_project_overview_employee_result` 做数据库分页，不走全量查询后截断
- 排序规则继续沿用现有口径，不新增筛选条件
### 前端
- `PreliminaryCheck.vue` 首屏固定请求第一页，每页 5 条
- `RiskPeopleSection.vue` 改为消费 `rows` 分页数据并新增分页条
- 翻页时仅刷新风险总览员工列表，不重载风险仪表盘、风险模型和风险明细
## 边界约束
- 不新增 `risk-people/page` 之类的补丁接口
- 不在前端做本地数组切片分页
- 不修改风险等级、命中模型数、核心异常点的业务口径
- 不删除现有 `top-risk-people` 接口
- 本次仅完成设计沉淀，尚未进入代码实施
## 说明
- 设计文档已按仓库规范保存到 `docs/design/`
- 由于仓库协作约定禁止开启 subagent，本次不走技能中的 subagent 评审环节，改为人工复核文档后进入后续实施计划阶段