ccdi/docs/design/2026-03-30-project-detail-risk-people-export-design.md

# 项目详情风险总览人员列表导出设计文档

**模块**: 项目详情 - 结果总览 - 风险总览人员列表导出  
**日期**: 2026-03-30  
**作者**: Codex  
**状态**: 已确认

## 一、背景

当前项目详情页 `结果总览 -> 风险总览` 中的人员列表已经支持分页展示与“查看项目”操作，但列表上方的“导出”按钮仍未接入真实导出能力。

结合现有页面语义与本次确认结果，本轮需求要求：

1. 在 `开发风险总览` 的人员列表中补齐真实导出能力。
2. 导出范围为当前项目下的全部风险人员，而不是当前分页 5 条。
3. 导出字段口径必须与页面表格保持一致。
4. 导出文件中不包含“操作”列。

## 二、目标

本次设计目标如下：

1. 为风险总览人员列表新增独立导出接口。
2. 前端点击“导出”按钮后可直接下载 Excel 文件。
3. 导出字段与页面展示字段保持一致：
   - 姓名
   - 身份证号
   - 所属部门
   - 疑似违规数
   - 风险等级
   - 命中模型数
   - 核心异常点
4. 分页展示与导出逻辑解耦，翻页不影响导出范围。

## 三、范围

### 3.1 本次范围

- 新增风险总览人员列表导出接口
- 新增风险总览人员导出 Excel 对象
- 为前端“导出”按钮绑定真实下载动作
- 补充本次设计文档，以及后续前后端实施计划入口

### 3.2 不在本次范围

- 不新增筛选条件、排序条件、搜索条件
- 不修改风险总览人员列表当前分页查询逻辑
- 不修改风险模型区、风险明细区功能
- 不修改人员详情、项目分析弹窗链路
- 不新增导出确认弹窗、二次筛选或降级方案

## 四、现状分析

### 4.1 前端现状

当前核心组件为：

- `ruoyi-ui/src/views/ccdiProject/components/detail/RiskPeopleSection.vue`

当前组件已经具备：

1. 表格字段展示
2. “查看项目”操作
3. 固定每页 5 条的分页能力
4. 顶部“导出”按钮文案

但当前“导出”按钮尚未绑定点击事件，也未接入下载接口。

### 4.2 后端现状

当前结果总览控制器为：

- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/controller/CcdiProjectOverviewController.java`

已具备以下相关能力：

1. `GET /ccdi/project/overview/risk-people`：分页查询风险人员总览
2. `POST /ccdi/project/overview/suspicious-transactions/export`：导出涉疑交易明细
3. `POST /ccdi/project/overview/risk-details/export`：统一导出风险明细

说明当前结果总览域内已经存在标准后端导出模式：

- 控制器暴露导出接口
- 服务层返回导出行对象列表
- 使用 `ExcelUtil` 输出 Excel 文件

风险人员列表本身已经有稳定的查询与字段组装逻辑：

1. 服务层通过 `getRiskPeopleOverview(CcdiProjectRiskPeopleQueryDTO queryDTO)` 查询分页数据
2. 使用 `buildRiskPeopleItem(projectId, aggregate)` 统一组装单行字段

因此，本次导出最合理的方式是复用现有字段组装逻辑，而不是重新设计一套独立口径。

## 五、方案对比

### 5.1 方案 A：新增后端导出接口，复用现有人员字段组装逻辑

做法：

- 新增 `POST /ccdi/project/overview/risk-people/export`
- 前端导出按钮直接调用下载接口
- 后端按当前项目查询全部风险人员
- 复用现有人员列表组装逻辑，再映射到 Excel 对象

优点：

- 最符合当前仓库导出模式
- 前端改动最小
- 页面字段与导出口径最容易保持一致
- 不会把分页展示逻辑和导出逻辑耦合在一起

缺点：

- 需要补一个导出 Excel 对象与对应测试

### 5.2 方案 B：前端请求超大分页，自行导出 Excel

做法：

- 点击导出时调用 `risk-people` 接口并传超大 `pageSize`
- 前端拿到全量数据后自行生成文件

问题：

- 不符合当前仓库常用导出模式
- 页面查询接口与导出职责混杂
- 前端文件生成链路与现有维护方式不一致

### 5.3 方案 C：新增导出接口，但单独写一套导出 SQL 和字段组装

做法：

- 后端新写独立导出查询
- 页面查询与导出查询分别维护

问题：

- 页面与导出会形成两套口径
- 后续字段扩展时最容易出现偏移
- 不符合最短路径要求

### 5.4 结论

采用 **方案 A：新增后端导出接口，复用现有人员字段组装逻辑**。

## 六、总体设计

### 6.1 交互链路

点击“导出”后的数据流如下：

1. 用户在 `RiskPeopleSection.vue` 点击“导出”按钮。
2. 前端通过 `this.download(...)` 调用新的后端导出接口。
3. 前端仅传 `projectId`，不传当前页码、页大小等分页参数。
4. 控制器接收请求后调用 `overviewService.exportRiskPeopleOverview(projectId)`。
5. 服务层校验项目存在后，查询当前项目下全部风险人员。
6. 服务层复用现有风险人员字段组装逻辑，生成 Excel 行对象列表。
7. 控制器使用 `ExcelUtil` 输出 `xlsx` 文件。

### 6.2 导出范围

导出范围固定为：

- 当前项目下的全部风险人员

说明：

- 不受当前分页影响
- 不只导出当前页 5 条
- 不增加额外筛选条件

### 6.3 导出字段

导出列固定如下：

1. 姓名
2. 身份证号
3. 所属部门
4. 疑似违规数
5. 风险等级
6. 命中模型数
7. 核心异常点

约束：

- 不导出“操作”列
- 不导出页面专用辅助字段，例如 `riskLevelType`
- 核心异常点展示口径需与页面一致

## 七、后端设计

### 7.1 控制器

在 `CcdiProjectOverviewController` 中新增导出接口：

- `POST /ccdi/project/overview/risk-people/export`

接口入参：

- `projectId`

权限控制沿用当前结果总览域的查询权限，不单独新增本轮设计范围外的权限体系。

### 7.2 服务层

在 `ICcdiProjectOverviewService` 与实现类中新增方法：

- `List<CcdiProjectRiskPeopleOverviewExcel> exportRiskPeopleOverview(Long projectId)`

服务层职责：

1. 校验项目存在
2. 查询当前项目全部风险人员
3. 复用现有人员列表字段组装逻辑
4. 将页面字段映射为导出对象
5. 返回 Excel 数据列表

### 7.3 查询策略

导出查询不复用当前分页接口返回值，也不走前端多页聚合。

建议实现方式：

1. 后端直接基于现有风险人员数据来源查询当前项目全部记录
2. 排序口径与分页列表保持一致：
   - `risk_level_sort asc`
   - `model_count desc`
   - `rule_count desc`
   - `staff_id_card asc`

这样可以保证页面与导出的记录顺序一致。

### 7.4 导出对象

新增导出对象：

- `CcdiProjectRiskPeopleOverviewExcel`

字段包含：

- `name`
- `idNo`
- `department`
- `riskCount`
- `riskLevel`
- `modelCount`
- `riskPoint`

其中：

- `riskPoint` 需要输出与页面“核心异常点”一致的文本口径
- 如果页面当前优先使用 `riskPointTagList` 组装展示，则导出时也应使用同样的归并顺序

## 八、前端设计

### 8.1 API 封装

在 `ruoyi-ui/src/api/ccdi/projectOverview.js` 中新增导出调用入口，供组件通过 `this.download(...)` 使用。

接口路径：

- `ccdi/project/overview/risk-people/export`

### 8.2 组件交互

在 `RiskPeopleSection.vue` 中：

1. 为当前“导出”按钮绑定点击事件
2. 点击后调用下载方法
3. 仅传 `projectId`
4. 文件名统一使用时间戳后缀

建议文件名：

- `风险人员总览_<timestamp>.xlsx`

### 8.3 交互约束

- 不新增确认弹窗
- 不新增 loading 外挂交互
- 不修改现有分页逻辑
- 不影响“查看项目”按钮行为

## 九、异常处理

本次导出错误处理遵循结果总览当前后端风格：

1. `projectId` 为空或项目不存在时，导出直接失败。
2. 查询异常或 Excel 生成异常时，导出整体失败。
3. 不生成空白文件作为兜底结果。
4. 不引入静默降级或兼容性补丁分支。

字段空值处理约束：

- 若部分字段为空，按现有页面语义导出为空字符串或统一文本结果
- 不因单行字段为空而跳过整行

## 十、测试口径

### 10.1 后端验证

需要验证：

1. 新增导出接口路径正确，且能委托到服务层
2. 导出服务会校验项目存在
3. 导出结果为当前项目全部风险人员，而不是当前页
4. 导出字段顺序与名称正确
5. 导出数据口径与页面表格一致

### 10.2 前端验证

需要验证：

1. “导出”按钮已绑定下载动作
2. 下载请求只传 `projectId`
3. 翻页功能仍正常
4. “查看项目”功能仍正常

## 十一、实施计划输出要求

根据仓库约定，进入实施阶段时默认同步输出两份实施计划：

1. 后端实施计划：`docs/plans/backend/`
2. 前端实施计划：`docs/plans/frontend/`

同时补充：

- 实施记录：`docs/reports/implementation/`
- 测试记录：`docs/tests/records/`

## 十二、结论

本次功能采用“后端新增导出接口 + 复用现有风险人员字段组装逻辑 + 前端按钮直连下载”的实现方式。

该方案满足以下要求：

1. 导出范围为当前项目全部风险人员
2. 导出字段与页面口径一致
3. 不引入额外筛选、补丁或兼容性分支
4. 改动路径短，符合当前仓库的导出实现风格