9.3 KiB
9.3 KiB
项目详情风险明细统一导出设计文档
日期: 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 服务职责
统一导出服务方法负责：
- 校验项目存在
- 查询涉疑交易全量导出数据
- 查询员工负面征信全量导出数据
- 构建包含三个 sheet 的 Excel 工作簿
- 输出到响应流
8.3 数据查询口径
1. 涉疑交易明细
- 沿用现有项目结果总览专用查询口径
- 不使用分页
- 不受页面当前涉疑类型筛选限制
- 导出当前项目全部命中记录
2. 员工负面征信信息
- 沿用现有项目员工负面征信查询口径
- 以
ccdi_project_overview_employee_result中当前项目员工为范围 - 关联
ccdi_credit_negative_info - 仅导出存在负面征信记录的员工
- 不使用分页
3. 异常账户人员信息
- 本次不做真实查询
- 仅输出空白 sheet 表头
9. Excel 结构设计
9.1 Sheet 顺序
工作簿固定包含以下三个 sheet，顺序不能变化：
涉疑交易明细员工负面征信信息异常账户人员信息
9.2 涉疑交易明细字段
字段固定为：
交易时间可疑人员关联人关联员工关系摘要/交易类型交易金额
9.3 员工负面征信信息字段
字段固定为：
员工姓名身份证号最近征信查询日期民事案件笔数民事案件金额强制执行笔数强制执行金额行政处罚笔数行政处罚金额
9.4 异常账户人员信息字段
字段固定为：
账号开户人银行异常类型异常发生时间状态
本次只输出表头，不输出数据行。
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 先保留空白模板，等待后续真实能力接入
该方案不引入补丁式兼容逻辑，不扩大需求范围，且能够在当前代码结构下稳定落地。