diff --git a/docs/design/2026-03-20-results-overview-risk-people-merge-design.md b/docs/design/2026-03-20-results-overview-risk-people-merge-design.md new file mode 100644 index 00000000..711b28be --- /dev/null +++ b/docs/design/2026-03-20-results-overview-risk-people-merge-design.md @@ -0,0 +1,319 @@ +# 结果总览风险人员区块收口设计文档 + +**模块**: 初核项目详情 - 结果总览 +**日期**: 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. 排序、风险等级计算和其他区块保持不变 + +该方案满足需求、口径单一、改动边界清晰,且不会把本轮调整扩散到结果总览其他功能块。