ccdi/docs/superpowers/specs/2026-03-30-project-detail-risk-details-unified-export-design.md

# 项目详情风险明细统一导出设计文档

**日期**: 2026-03-30  
**模块**: 项目详情 - 结果总览 - 风险明细  
**作者**: Codex  
**状态**: 已确认

## 1. 背景

当前项目详情页的 `结果总览 -> 风险明细` 已具备以下现状：

- `涉疑交易明细` 已接入真实分页查询，并具备单独导出能力
- `员工负面征信信息` 已接入真实分页查询，但没有导出能力
- `异常账户人员信息` 仍为占位展示，尚未开发真实查询链路

现有导出能力存在两个问题：

- 导出入口分散在区块内，语义上更像“局部导出”，不符合风险明细整体导出的业务动作
- 风险明细三个区块无法一次性导出到同一个 Excel 文件中

本次目标是在不扩展异常账户真实查询范围的前提下，为风险明细新增一个统一导出入口，将风险明细内容导出为一个包含三个 sheet 的 Excel 文件。

## 2. 目标

- 在 `风险明细` 总卡片右上角新增统一导出按钮
- 移除三个区块内已有或占位的单独导出按钮
- 点击后导出一个 Excel 文件，固定包含三个 sheet
- 导出当前项目下风险明细的全部命中记录，不受页面分页限制
- `异常账户人员信息` 本次仅保留空白 sheet，不开发真实查询链路

## 3. 范围

### 3.1 包含范围

- 风险明细区域统一导出按钮改造
- 新增结果总览统一导出接口
- 生成包含三个 sheet 的 Excel 文件
- 复用现有涉疑交易导出数据口径
- 新增员工负面征信导出数据口径
- 为异常账户预留空白 sheet 和表头

### 3.2 不包含范围

- 不开发异常账户人员信息的真实查询、分页与详情能力
- 不改造项目分析弹窗
- 不新增异步导出任务或下载中心
- 不新增筛选条件、导出类型选择或二次确认弹窗
- 不调整其他页面或其他模块的导出逻辑

## 4. 已确认口径

### 4.1 导出入口位置

- 统一导出按钮放在 `风险明细` 总卡片右上角
- `涉疑交易明细`、`员工负面征信信息`、`异常账户人员信息` 三个区块内都不再保留单独导出按钮

### 4.2 导出范围

- 导出当前项目下三类数据的全部命中记录
- 不受当前分页限制
- 不以页面当前分页页码作为导出口径

### 4.3 异常账户处理方式

- `异常账户人员信息` 本次暂不开发真实数据
- 导出文件中必须保留 `异常账户人员信息` sheet
- sheet 只保留表头，不输出数据行
- 不使用 mock 数据或伪造占位数据填充导出内容

## 5. 方案对比

### 方案 A：新增统一导出接口，由后端一次性生成 3 个 sheet

- 前端只负责触发一次下载
- 后端统一查询、统一组装 Excel
- 异常账户 sheet 直接输出空白模板

优点：

- 语义清晰，和“风险明细整体导出”完全一致
- 最短路径满足业务目标
- 前后端职责清楚，页面展示逻辑与导出逻辑边界明确

缺点：

- 需要补一个工作簿级别的导出实现

### 方案 B：保留三条独立导出链路，再额外拼统一导出

- 各区块维持独立导出能力
- 统一导出再调用多条现有导出逻辑

优点：

- 表面上复用较多

缺点：

- 职责交叉，维护复杂
- 与“移除单独导出入口”的确认结果不一致

### 方案 C：由前端分别取三份数据，再请求后端生成文件

- 前端承担更多数据编排责任

优点：

- 后端接口表面更少

缺点：

- 前端与导出逻辑耦合过深
- 不适合“导出全部命中记录”的独立口径

## 6. 最终方案

采用 **方案 A：新增统一导出接口，由后端一次性生成包含 3 个 sheet 的 Excel 文件**。

选择原因：

- 完全符合“风险明细整体导出”的操作语义
- 不把页面当前筛选或分页状态强绑到导出逻辑
- 可以在不开发异常账户真实数据的前提下先完成导出闭环

## 7. 前端设计

### 7.1 页面位置

页面改动集中在：

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

### 7.2 交互设计

- 在 `风险明细` 总卡片右上角新增统一 `导出` 按钮
- 移除 `涉疑交易明细` 区块右上角现有导出按钮
- 移除 `异常账户人员信息` 区块右上角占位导出按钮
- `员工负面征信信息` 区块保持无局部导出按钮

### 7.3 触发规则

- 当 `projectId` 存在时允许触发导出
- 点击后直接下载 `.xlsx` 文件
- 不增加确认弹窗
- 不增加导出类型选择
- 不增加导出异步任务轮询

### 7.4 文件命名

导出文件命名建议为：

- `风险明细_<项目ID>_<时间戳>.xlsx`

## 8. 后端设计

### 8.1 接口设计

在结果总览控制器下新增统一导出接口：

- 路径：`POST /ccdi/project/overview/risk-details/export`
- 入参：
  - `projectId`
- 权限：`ccdi:project:query`
- 返回：文件流

本次接口不接收 `suspiciousType`，因为导出口径固定为当前项目的全部命中记录。

### 8.2 服务职责

统一导出服务方法负责：

1. 校验项目存在
2. 查询涉疑交易全量导出数据
3. 查询员工负面征信全量导出数据
4. 构建包含三个 sheet 的 Excel 工作簿
5. 输出到响应流

### 8.3 数据查询口径

#### 1. 涉疑交易明细

- 沿用现有项目结果总览专用查询口径
- 不使用分页
- 不受页面当前涉疑类型筛选限制
- 导出当前项目全部命中记录

#### 2. 员工负面征信信息

- 沿用现有项目员工负面征信查询口径
- 以 `ccdi_project_overview_employee_result` 中当前项目员工为范围
- 关联 `ccdi_credit_negative_info`
- 仅导出存在负面征信记录的员工
- 不使用分页

#### 3. 异常账户人员信息

- 本次不做真实查询
- 仅输出空白 sheet 表头

## 9. Excel 结构设计

### 9.1 Sheet 顺序

工作簿固定包含以下三个 sheet，顺序不能变化：

1. `涉疑交易明细`
2. `员工负面征信信息`
3. `异常账户人员信息`

### 9.2 涉疑交易明细字段

字段固定为：

1. `交易时间`
2. `可疑人员`
3. `关联人`
4. `关联员工`
5. `关系`
6. `摘要/交易类型`
7. `交易金额`

### 9.3 员工负面征信信息字段

字段固定为：

1. `员工姓名`
2. `身份证号`
3. `最近征信查询日期`
4. `民事案件笔数`
5. `民事案件金额`
6. `强制执行笔数`
7. `强制执行金额`
8. `行政处罚笔数`
9. `行政处罚金额`

### 9.4 异常账户人员信息字段

字段固定为：

1. `账号`
2. `开户人`
3. `银行`
4. `异常类型`
5. `异常发生时间`
6. `状态`

本次只输出表头，不输出数据行。

## 10. 实现建议

### 10.1 Excel 生成方式

现有 `ExcelUtil.exportExcel(response, list, sheetName)` 主要面向单 sheet 导出。本次统一导出建议采用工作簿级别写法，直接生成多 sheet 文件，而不是强行拼接多个单 sheet 导出调用。

### 10.2 复用策略

- `涉疑交易明细` 复用现有导出查询和行对象组装逻辑
- `员工负面征信信息` 新增独立 Excel 行对象和导出查询
- `异常账户人员信息` 新增仅包含表头的 sheet 构建逻辑

## 11. 异常处理

- `projectId` 为空或项目不存在时，直接返回业务错误
- 导出过程中如真实数据查询失败，则整个导出失败，不输出半成品文件
- `异常账户人员信息` sheet 为空属于正常结果
- 若三个 sheet 都无数据，仍导出一个包含三张表头的空模板文件

## 12. 测试设计

### 12.1 前端测试

- 风险明细总卡片右上角显示统一导出按钮
- 三个区块内部单独导出按钮全部移除
- 点击统一导出后触发文件下载
- 不影响涉疑交易筛选、分页和详情弹窗
- 不影响员工负面征信分页

### 12.2 后端测试

- 有效 `projectId` 可成功返回 `.xlsx` 文件
- 工作簿包含 3 个 sheet，且顺序正确
- `涉疑交易明细` sheet 数据条数与当前项目全量命中记录一致
- `员工负面征信信息` sheet 数据条数与当前项目全量命中记录一致
- `异常账户人员信息` sheet 只有表头、无数据行
- 无效 `projectId` 返回失败

### 12.3 回归验证

- 若保留原涉疑交易单独导出接口，确认项目详情页不再使用旧入口
- 若替换原入口，确认没有其他页面依赖该按钮交互

## 13. 文档落点

本需求相关文档建议落点如下：

- 设计文档：`docs/superpowers/specs/2026-03-30-project-detail-risk-details-unified-export-design.md`
- 后端实施计划：`docs/plans/backend/2026-03-30-project-detail-risk-details-unified-export-implementation-plan.md`
- 前端实施计划：`docs/plans/frontend/2026-03-30-project-detail-risk-details-unified-export-implementation-plan.md`
- 后端实施记录：`docs/reports/implementation/2026-03-30-project-detail-risk-details-unified-export-backend-implementation.md`
- 前端实施记录：`docs/reports/implementation/2026-03-30-project-detail-risk-details-unified-export-frontend-implementation.md`

## 14. 结论

本次按最短路径完成 `风险明细` 统一导出闭环：

- 前端收口为一个统一导出入口
- 后端输出一个 3-sheet Excel 文件
- 涉疑交易与员工负面征信导出真实数据
- 异常账户人员信息 sheet 先保留空白模板，等待后续真实能力接入

该方案不引入补丁式兼容逻辑，不扩大需求范围，且能够在当前代码结构下稳定落地。