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

**模块**: 初核项目详情 - 结果总览
**日期**: 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. 排序、风险等级计算和其他区块保持不变

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