新增风险明细员工负面征信设计文档

2026-03-28 16:03:17 +08:00
parent cf36b5f05a
commit c1018fea0c
2 changed files with 305 additions and 0 deletions
--- a/docs/reports/implementation/2026-03-28-risk-detail-employee-credit-negative-design-record.md
+++ b/docs/reports/implementation/2026-03-28-risk-detail-employee-credit-negative-design-record.md
@@ -0,0 +1,19 @@
+# 风险明细员工负面征信设计记录
+
+## 本次改动
+
+- 新增设计文档 `docs/superpowers/specs/2026-03-28-risk-detail-employee-credit-negative-design.md`
+- 明确结果总览风险明细中新增 `员工负面征信信息` 区块
+- 明确员工范围沿用 `ccdi_project_overview_employee_result`
+- 明确只展示 `ccdi_credit_negative_info` 负面信息，不接入负债明细
+- 明确前端采用单表格直出全部负面字段，不做展开
+
+## 设计结论
+
+- 采用结果总览专用接口新增项目维度员工负面征信查询能力
+- 不复用全局征信维护列表接口
+- 后续实施阶段需要分别输出前端、后端两份实施计划
+
+## 备注
+
+- 按当前仓库约定，本次仅沉淀设计与改动记录，实施计划待设计审阅通过后继续输出
--- a/docs/superpowers/specs/2026-03-28-risk-detail-employee-credit-negative-design.md
+++ b/docs/superpowers/specs/2026-03-28-risk-detail-employee-credit-negative-design.md
@@ -0,0 +1,286 @@
+# 风险明细员工负面征信设计文档
+
+**日期**: 2026-03-28  
+**模块**: 项目详情 - 结果总览 - 风险明细  
+**作者**: Codex  
+**状态**: 已确认
+
+## 1. 背景
+
+当前项目详情页的 `结果总览 -> 风险明细` 中，已经具备：
+
+- 上方 `涉疑交易明细` 真实列表
+- 下方 `异常账户人员信息` 占位区块
+
+同时，系统内已经存在独立的征信维护能力：
+
+- 负面信息表：`ccdi_credit_negative_info`
+- 维护页面：`/ccdi/creditInfo`
+
+但风险明细区域还没有把“项目内员工”的负面征信信息展示出来。当前需求是在 `涉疑交易明细` 下方新增一个员工负面征信区块，用于展示当前项目结果总览口径内员工的负面征信信息。
+
+## 2. 目标
+
+- 在风险明细卡片内新增 `员工负面征信信息` 区块
+- 展示当前项目结果总览口径内员工的负面征信信息
+- 只展示负面征信信息，不混入负债明细
+- 保持最短路径实现，不跳转、不展开、不引入额外摘要卡片
+
+## 3. 范围
+
+### 3.1 包含范围
+
+- 结果总览 `风险明细` 区域新增员工负面征信列表
+- 结果总览专用后端分页查询接口
+- 项目员工范围与负面征信表的聚合查询 SQL
+- 前端列表展示、分页与空态
+
+### 3.2 不包含范围
+
+- 不改造现有征信维护页面
+- 不接入负债明细
+- 不做行内展开、详情弹窗、跳转项目分析
+- 不新增项目外员工查询逻辑
+- 不增加原型外统计卡片、筛选器或导出能力
+
+## 4. 已确认口径
+
+### 4.1 区块位置
+
+- 新区块放在 `涉疑交易明细` 下方
+- 保持在同一个 `风险明细` 卡片内
+- 不放到 `项目分析` 弹窗或其他页签中
+
+### 4.2 员工范围
+
+- 员工集合沿用结果总览当前口径
+- 以 `ccdi_project_overview_employee_result` 中当前项目员工为准
+- 不扩大到项目配置中的全部目标员工
+- 不收窄为仅涉疑交易涉及员工
+
+### 4.3 展示形态
+
+- 直接表格展示
+- 一行一个员工
+- 不做展开
+- 负面信息全部字段直接放在列表中
+
+### 4.4 数据范围
+
+- 只展示 `ccdi_credit_negative_info` 负面信息
+- 不展示 `ccdi_debts_info` 负债明细
+- 只保留当前项目员工中“存在负面征信记录”的员工
+- 没有负面征信记录的员工不展示空行
+
+## 5. 方案对比
+
+### 方案 A：风险明细内新增独立负面征信表格区块
+
+- 在 `RiskDetailSection.vue` 中新增第二个真实业务表格
+- 后端新增项目维度专用查询接口
+- 前端直接展示负面信息全部字段
+
+优点：
+
+- 与需求位置完全一致
+- 阅读路径最短
+- 语义清晰，不污染全局征信维护页面
+
+缺点：
+
+- 需要新增一条结果总览专用查询链路
+
+### 方案 B：主表摘要 + 展开查看负面信息
+
+- 主表先展示员工摘要
+- 点击后再展开负面明细
+
+优点：
+
+- 页面更轻
+
+缺点：
+
+- 与“所有字段直接放列表里”的确认结果不一致
+- 增加额外交互层级
+
+### 方案 C：接入项目分析弹窗中的征信摘要页签
+
+- 不在风险明细新增区块
+- 改为真实化 `项目分析 -> 征信摘要`
+
+优点：
+
+- 与人员分析语义更统一
+
+缺点：
+
+- 不符合“放在涉疑交易明细下面”的位置要求
+- 用户路径变长
+
+## 6. 最终方案
+
+采用 **方案 A：在风险明细内新增独立员工负面征信表格区块**。
+
+选择原因：
+
+- 完全符合用户确认的位置与交互要求
+- 最短路径满足业务目标
+- 只需要补一条项目维度查询接口，不需要推翻现有征信维护链路
+
+## 7. 前端设计
+
+## 7.1 页面位置
+
+页面位置固定在：
+
+- `ruoyi-ui/src/views/ccdiProject/components/detail/RiskDetailSection.vue`
+
+结构顺序调整为：
+
+1. `涉疑交易明细`
+2. `员工负面征信信息`
+3. `异常账户人员信息`
+
+## 7.2 区块标题
+
+- 区块标题：`员工负面征信信息`
+- 区块副标题：`展示当前项目员工的负面征信信息`
+
+## 7.3 表格字段
+
+列表字段固定为：
+
+1. `员工姓名`
+2. `身份证号`
+3. `最近征信查询日期`
+4. `民事案件笔数`
+5. `民事案件金额`
+6. `强制执行笔数`
+7. `强制执行金额`
+8. `行政处罚笔数`
+9. `行政处罚金额`
+
+以上字段全部来源于 `ccdi_credit_negative_info` 的现有业务字段，不新增派生字段。
+
+## 7.4 展示规则
+
+- 一行一个员工
+- 金额列右对齐
+- 日期列固定宽度
+- 身份证号支持表格常规溢出处理
+- 不提供展开、详情按钮、导出按钮
+
+## 7.5 空态与分页
+
+- 仅当列表为空时显示空态
+- 空态文案：`当前项目暂无员工负面征信信息`
+- 支持分页
+- 分页交互与上方涉疑交易列表独立
+
+## 8. 后端设计
+
+## 8.1 接口设计
+
+在结果总览控制器下新增专用接口：
+
+### 1. 查询员工负面征信信息
+
+- 路径：`GET /ccdi/project/overview/employee-credit-negative`
+- 入参：
+  - `projectId`
+  - `pageNum`
+  - `pageSize`
+- 出参：
+  - `rows`
+  - `total`
+
+本次不新增导出接口。
+
+## 8.2 查询口径
+
+查询分两层组织：
+
+### 第一层：项目员工范围
+
+员工范围直接取自结果总览员工结果表：
+
+- 表：`ccdi_project_overview_employee_result`
+- 条件：`project_id = 当前项目`
+
+该层只负责限定当前项目员工集合。
+
+### 第二层：负面征信命中
+
+将项目员工集合与 `ccdi_credit_negative_info` 做关联：
+
+- 关联键：`staff_id_card = person_id`
+- 只保留匹配到负面征信记录的员工
+
+展示字段取值规则：
+
+- `员工姓名`：优先取 `ccdi_credit_negative_info.person_name`
+- 若负面征信姓名为空，可回退 `ccdi_project_overview_employee_result.staff_name`
+- 其余负面字段直接取 `ccdi_credit_negative_info` 对应列
+
+## 8.3 排序规则
+
+固定排序：
+
+1. `query_date` 倒序
+2. `person_id` 升序
+
+不增加前端自定义排序条件。
+
+## 8.4 职责边界
+
+- 不复用 `/ccdi/creditInfo/list`
+- 不把项目口径硬塞进征信维护模块的现有接口
+- 结果总览接口只负责“项目内员工负面征信展示”
+- 征信维护接口继续负责“全局征信对象维护”
+
+## 9. 数据流
+
+整体链路如下：
+
+`RiskDetailSection.vue -> projectOverview API -> CcdiProjectOverviewController -> CcdiProjectOverviewService -> CcdiProjectOverviewMapper -> ccdi_project_overview_employee_result + ccdi_credit_negative_info`
+
+职责说明：
+
+- 前端只负责区块展示与分页
+- Controller 负责暴露结果总览专用接口
+- Service 负责项目存在性校验、分页组装
+- Mapper 负责项目员工范围与负面征信表聚合查询
+
+## 10. 测试设计
+
+### 10.1 前端测试
+
+- 风险明细中新增 `员工负面征信信息` 区块
+- 列表字段顺序与设计一致
+- 空列表时展示指定空态文案
+- 分页与上方涉疑交易列表互不干扰
+
+### 10.2 后端测试
+
+- 项目内员工存在负面征信记录时可正常查询
+- 项目内员工无负面征信记录时不返回空记录
+- 项目外员工负面征信记录不会混入结果
+- 查询结果不包含负债明细字段
+- 排序按 `query_date desc, person_id asc`
+
+## 11. 实施边界
+
+本次只覆盖结果总览风险明细中的员工负面征信展示：
+
+- 不改征信维护菜单与权限
+- 不改征信上传与覆盖写入逻辑
+- 不新增负面征信统计卡片
+- 不新增项目分析页签真实化改造
+
+## 12. 后续动作
+
+待用户审阅本设计文档后，按仓库约定继续输出两份实施计划：
+
+- `docs/plans/backend/` 后端实施计划
+- `docs/plans/frontend/` 前端实施计划