ccdi/docs/design/2026-03-20-results-overview-risk-people-merge-design.md

结果总览风险人员区块收口设计文档

模块: 初核项目详情 - 结果总览 日期: 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

调整后示例：

{
  "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. 排序、风险等级计算和其他区块保持不变

该方案满足需求、口径单一、改动边界清晰，且不会把本轮调整扩散到结果总览其他功能块。