320 lines
7.5 KiB
Markdown
320 lines
7.5 KiB
Markdown
# 结果总览风险人员区块收口设计文档
|
||
|
||
**模块**: 初核项目详情 - 结果总览
|
||
**日期**: 2026-03-20
|
||
|
||
## 一、背景
|
||
|
||
当前结果总览页面的人员相关信息拆分为两个区块：
|
||
|
||
- 风险人员总览
|
||
- 中高风险人员TOP10
|
||
|
||
现状问题是：
|
||
|
||
1. 风险等级、命中模型数只在 `中高风险人员TOP10` 中展示。
|
||
2. 风险人员总览与 TOP10 在页面上存在信息拆散，用户需要跨区块比对。
|
||
3. 本轮需求要求移除独立的 TOP10 区块，并把关键风险字段收拢到风险人员总览中。
|
||
|
||
## 二、目标
|
||
|
||
本次设计目标如下：
|
||
|
||
1. 移除结果总览页面中的 `中高风险人员TOP10` 区块。
|
||
2. 保留 `风险人员总览` 作为唯一人员榜单区块。
|
||
3. 在风险人员总览现有列基础上新增：
|
||
- `风险等级`
|
||
- `命中模型数`
|
||
4. 保持当前风险人员总览的排序逻辑不变。
|
||
|
||
## 三、范围
|
||
|
||
### 3.1 本次范围
|
||
|
||
- 调整结果总览页面人员区块结构
|
||
- 扩展风险人员总览接口返回字段
|
||
- 移除结果总览页面对 TOP10 接口的依赖
|
||
- 更新前端静态断言测试
|
||
- 补充本次设计文档、后续前后端实施计划与实施记录
|
||
|
||
### 3.2 不在本次范围
|
||
|
||
- 不调整风险仪表盘区块
|
||
- 不调整风险模型区和风险明细区
|
||
- 不修改风险等级计算规则
|
||
- 不修改风险人员总览当前排序口径
|
||
- 不在本轮删除后端独立 TOP10 接口
|
||
|
||
## 四、现状分析
|
||
|
||
### 4.1 页面现状
|
||
|
||
当前 `RiskPeopleSection.vue` 中包含两个 block：
|
||
|
||
1. `风险人员总览`
|
||
2. `中高风险人员TOP10`
|
||
|
||
风险人员总览当前展示字段为：
|
||
|
||
- 姓名
|
||
- 身份证号
|
||
- 所属部门
|
||
- 疑似违规数
|
||
- 核心异常点
|
||
- 操作
|
||
|
||
TOP10 当前展示字段为：
|
||
|
||
- 姓名
|
||
- 身份证号
|
||
- 所属部门
|
||
- 风险等级
|
||
- 命中模型数
|
||
- 操作
|
||
|
||
### 4.2 后端现状
|
||
|
||
后端员工聚合结果 `CcdiProjectEmployeeRiskAggregateVO` 已经包含以下字段：
|
||
|
||
- `modelCount`
|
||
- `riskLevelCode`
|
||
- `riskLevelName`
|
||
- `riskLevelSort`
|
||
|
||
这说明本轮需求不需要新增新的统计口径，后端已有聚合结果足以支撑风险人员总览增加两列展示。
|
||
|
||
## 五、方案对比
|
||
|
||
### 5.1 方案 A：扩展风险人员总览接口并移除页面 TOP10 依赖
|
||
|
||
做法：
|
||
|
||
- 风险人员总览接口直接补充返回 `riskLevel`、`riskLevelType`、`modelCount`
|
||
- 前端页面只保留一个风险人员总览表格
|
||
- 前端不再请求 TOP10 接口
|
||
|
||
优点：
|
||
|
||
- 最短路径实现
|
||
- 字段来源单一，口径一致
|
||
- 不需要前端做补丁式字段拼装
|
||
- 与本轮“移除 TOP10 页面区块”的需求完全一致
|
||
|
||
缺点：
|
||
|
||
- 风险人员总览表格横向字段增加，需要适度调整列宽
|
||
|
||
### 5.2 方案 B：前端继续请求 TOP10，再回填到风险人员总览
|
||
|
||
做法：
|
||
|
||
- 风险人员总览接口不变
|
||
- 前端同时请求风险人员总览和 TOP10
|
||
- 前端根据人员信息把风险等级和命中模型数拼回总览表格
|
||
|
||
问题：
|
||
|
||
- 字段来源分裂
|
||
- 口径容易漂移
|
||
- 属于补丁式方案，不符合本次最短路径和单一口径要求
|
||
|
||
### 5.3 方案 C：只隐藏 TOP10 区块，不补真实字段
|
||
|
||
做法：
|
||
|
||
- 页面隐藏 TOP10
|
||
- 风险人员总览接口和表格不扩展
|
||
|
||
问题：
|
||
|
||
- 无法满足“新增风险等级和命中模型数”的需求
|
||
- 需求不完整
|
||
|
||
### 5.4 结论
|
||
|
||
采用方案 A。
|
||
|
||
## 六、目标页面结构
|
||
|
||
人员区块调整后，结果总览页面仍保留四大区块：
|
||
|
||
1. 风险仪表盘
|
||
2. 风险人员总览
|
||
3. 风险模型
|
||
4. 风险明细
|
||
|
||
其中人员区块收口为单表结构，风险人员总览列顺序为：
|
||
|
||
1. 序号
|
||
2. 姓名
|
||
3. 身份证号
|
||
4. 所属部门
|
||
5. 疑似违规数
|
||
6. 风险等级
|
||
7. 命中模型数
|
||
8. 核心异常点
|
||
9. 操作
|
||
|
||
说明：
|
||
|
||
- `风险等级` 使用标签展示，继续直接绑定后端返回的 `riskLevelType`
|
||
- `命中模型数` 直接展示后端返回的 `modelCount`
|
||
- `核心异常点` 继续完整展示，不做压缩式改造
|
||
|
||
## 七、后端设计
|
||
|
||
### 7.1 接口边界
|
||
|
||
继续沿用现有接口：
|
||
|
||
- `GET /ccdi/project/overview/risk-people`
|
||
|
||
入参不变：
|
||
|
||
- `projectId`
|
||
|
||
### 7.2 返回结构调整
|
||
|
||
风险人员总览返回项新增以下字段：
|
||
|
||
- `riskLevel`
|
||
- `riskLevelType`
|
||
- `modelCount`
|
||
|
||
调整后示例：
|
||
|
||
```json
|
||
{
|
||
"overviewList": [
|
||
{
|
||
"name": "李四",
|
||
"idNo": "330000000000000001",
|
||
"department": "信息二部",
|
||
"riskCount": 5,
|
||
"riskLevel": "中风险",
|
||
"riskLevelType": "warning",
|
||
"modelCount": 4,
|
||
"riskPoint": "大额单笔收入、疑似兼职",
|
||
"actionLabel": "查看详情"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 7.3 聚合与映射
|
||
|
||
后端不新增新的聚合 SQL 口径，直接复用现有员工风险聚合结果：
|
||
|
||
- `hitCount` 继续作为 `riskCount`
|
||
- `riskLevelCode` 用于映射 `riskLevel` 和 `riskLevelType`
|
||
- `modelCount` 直接透传到风险人员总览项
|
||
|
||
服务层新增映射规则：
|
||
|
||
- `HIGH -> 高风险 / danger`
|
||
- `MEDIUM -> 中风险 / warning`
|
||
- `LOW -> 低风险 / info`
|
||
|
||
### 7.4 排序口径
|
||
|
||
风险人员总览继续沿用当前查询顺序：
|
||
|
||
- `risk_level_sort asc`
|
||
- `model_count desc`
|
||
- `rule_count desc`
|
||
- `staff_id_card asc`
|
||
|
||
本次不改成新的重点排序规则。
|
||
|
||
## 八、前端设计
|
||
|
||
### 8.1 页面结构调整
|
||
|
||
`RiskPeopleSection.vue` 中：
|
||
|
||
- 保留风险人员总览 block
|
||
- 删除中高风险人员TOP10 block
|
||
- 在风险人员总览表格中新增两列：
|
||
- 风险等级
|
||
- 命中模型数
|
||
|
||
### 8.2 数据装配调整
|
||
|
||
`PreliminaryCheck.vue` 中页面加载时：
|
||
|
||
- 保留 `dashboard` 请求
|
||
- 保留 `riskPeople` 请求
|
||
- 移除 `topRiskPeople` 请求
|
||
|
||
`createOverviewLoadedData` 中：
|
||
|
||
- 保留 `overviewList` 注入
|
||
- 移除 `topRiskList` 对页面展示的依赖
|
||
|
||
### 8.3 Mock 与状态数据
|
||
|
||
`preliminaryCheck.mock.js` 中：
|
||
|
||
- `overviewList` 示例数据补充 `riskLevel`、`riskLevelType`、`modelCount`
|
||
- 页面状态数据不再依赖 `topRiskList`
|
||
|
||
## 九、异常与空态处理
|
||
|
||
- `projectId` 为空时，继续展示现有空态
|
||
- 接口异常时，继续沿用当前结果总览页面的空态回退
|
||
- 风险人员总览无数据时，展示单表空态，不再出现第二个 TOP10 区块
|
||
- 风险等级标签由后端直接提供，不在前端新增业务推导逻辑
|
||
|
||
## 十、验证设计
|
||
|
||
### 10.1 后端验证
|
||
|
||
需要验证：
|
||
|
||
1. 风险人员总览接口返回新增字段：
|
||
- `riskLevel`
|
||
- `riskLevelType`
|
||
- `modelCount`
|
||
2. 风险等级口径保持原逻辑不变
|
||
3. 疑似违规数仍然来自 `hitCount`
|
||
4. 风险人员总览排序不变
|
||
|
||
### 10.2 前端验证
|
||
|
||
需要验证：
|
||
|
||
1. 结果总览页面不再请求 TOP10 接口
|
||
2. 人员区块只渲染一个表格
|
||
3. 风险人员总览出现新增两列：
|
||
- 风险等级
|
||
- 命中模型数
|
||
4. 加载态、空态、正常态均可正常展示
|
||
|
||
### 10.3 测试资产更新
|
||
|
||
前端静态断言测试需要同步调整：
|
||
|
||
- 移除对 `中高风险人员TOP10` 文案的依赖
|
||
- 增加对 `风险等级`、`命中模型数` 的断言
|
||
|
||
## 十一、文档沉淀
|
||
|
||
本次设计确认后，后续需补齐以下文档：
|
||
|
||
1. 后端实施计划：`docs/plans/backend/`
|
||
2. 前端实施计划：`docs/plans/frontend/`
|
||
3. 实施记录：`docs/reports/implementation/`
|
||
4. 验证记录：`docs/tests/records/`
|
||
|
||
## 十二、结论
|
||
|
||
本次改动采用“单表收口”的最短路径方案：
|
||
|
||
1. 页面移除独立的 `中高风险人员TOP10`
|
||
2. `风险人员总览` 补充 `风险等级` 与 `命中模型数`
|
||
3. 后端扩展现有风险人员总览接口返回字段
|
||
4. 前端移除对 TOP10 接口的页面依赖
|
||
5. 排序、风险等级计算和其他区块保持不变
|
||
|
||
该方案满足需求、口径单一、改动边界清晰，且不会把本轮调整扩散到结果总览其他功能块。
|