补充风险明细统一导出设计文档

docs/reports/implementation/2026-03-30-project-detail-risk-details-unified-export-design-record.md

@@ -0,0 +1,35 @@
+# 项目详情风险明细统一导出设计记录
+
+**日期**: 2026-03-30  
+**类型**: 设计记录  
+**范围**: 项目详情 - 结果总览 - 风险明细统一导出
+
+## 1. 本次变更内容
+
+新增正式设计文档：
+
+- `docs/superpowers/specs/2026-03-30-project-detail-risk-details-unified-export-design.md`
+
+设计结论如下：
+
+- 风险明细统一导出入口放在总卡片右上角
+- 移除三个区块内部单独导出按钮
+- 导出文件固定包含 `涉疑交易明细`、`员工负面征信信息`、`异常账户人员信息` 三个 sheet
+- 导出口径为当前项目下全部命中记录，不受当前分页限制
+- `异常账户人员信息` 本次保留空白 sheet，不开发真实数据链路
+
+## 2. 设计约束
+
+- 不扩展到其他页签或其他模块
+- 不新增导出异步任务和下载中心
+- 不在前端拼装 Excel
+- 不伪造异常账户 mock 数据
+
+## 3. 后续文档规划
+
+待用户确认设计文档后，继续补充：
+
+- 后端实施计划
+- 前端实施计划
+- 后端实施记录
+- 前端实施记录

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

@@ -0,0 +1,311 @@
+# 项目详情风险明细统一导出设计文档
+
+**日期**: 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 先保留空白模板，等待后续真实能力接入
+
+该方案不引入补丁式兼容逻辑，不扩大需求范围，且能够在当前代码结构下稳定落地。