# 开发风险明细涉疑交易明细设计

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

## 1. 背景

当前项目详情页的“结果总览”模块中，`RiskDetailSection.vue` 里的“涉险交易明细”仍为静态占位表格，字段、筛选和交互均未对齐需求原型。

根据 `README.md` 中“风险明细 -> 涉疑交易明细表”的描述，以及本轮确认结果，本次需要在“开发风险明细”中新增真实可用的“涉疑交易明细”能力，用于展示两类流水：

- 命中规则名称中包含“可疑”的流水
- 交易对手方命中中介库的流水

页面展示需与现有“流水明细查询”页面的表格样式、金额样式、查看详情细节保持一致。

## 2. 目标

- 在结果总览页内展示真实“涉疑交易明细”列表
- 支持按“全部可疑人员类型 / 名单库命中 / 模型规则命中”切换查看
- 同一条流水即使同时命中两类来源，也只展示一条
- 切换筛选类型时，同一条流水可被对应来源正常筛出
- 详情查看直接复用现有“流水明细查询”详情接口与弹窗

## 3. 范围

### 3.1 包含范围

- 结果总览页“风险明细”区块内的“涉疑交易明细”真实化
- 结果总览专用后端列表接口与导出接口
- 列表数据查询 SQL
- 页面下拉筛选与导出交互
- 与现有流水详情弹窗的复用对接

### 3.2 不包含范围

- 不新增页面路由
- 不改造通用“流水明细查询”列表接口语义
- 不新增中间结果表
- 不增加原型外的高级筛选项
- 不引入模糊名称匹配、兼容性兜底策略或扩展来源类型

## 4. 已确认口径

### 4.1 命中来源

涉疑交易明细只包含以下两类流水：

1. `模型规则命中`
   - 来源表：`ccdi_bank_statement_tag_result`
   - 口径：`rule_name` 包含“可疑”

2. `名单库命中`
   - 口径：交易对手方出现在中介库
   - 命中字段：身份证、名称、统一社会信用代码
   - 匹配方式：精确匹配
   - 命中范围：
     - 个人中介库
     - 实体中介库

### 4.2 去重规则

- 同一 `bank_statement_id` 在列表中只展示一条
- 同时命中“模型规则命中”和“名单库命中”时，不重复出两条
- 但需同时保留两类命中标识，以便在不同筛选类型下都能命中该流水

### 4.3 查看详情

- `查看详情` 直接复用现有“流水明细查询”的详情接口和详情弹窗
- 详情字段、样式和交互不另起新实现

## 5. 方案对比

### 方案一：结果总览专用涉疑交易接口

- 在结果总览模块下新增专用列表与导出接口
- 使用独立 SQL 聚合“规则命中”和“名单库命中”两类流水
- 前端只在结果总览页使用这组接口

优点：

- 语义清晰，和通用流水查询职责分离
- 变更集中，不污染现有明细查询链路
- 更容易保证“去重后仍可按来源筛出”的需求口径

缺点：

- 需要新增 DTO、VO、Mapper 查询方法和前端 API

### 方案二：在通用流水明细接口上增加涉疑模式

- 在现有 `CcdiBankStatementController` 列表接口中加入“涉疑”查询参数
- 一套接口兼顾通用查询和涉疑查询

优点：

- 前端列表和后端查询复用更多

缺点：

- 通用流水查询和结果总览业务语义混杂
- 导出、排序、字段映射和筛选会越来越难维护
- 后续扩展风险明细时容易继续耦合

### 方案三：先沉淀名单库命中结果表，再统一查询

- 将名单库命中的流水预先写入单独结果表
- 再与规则命中结果统一聚合

优点：

- 来源边界最清晰

缺点：

- 对当前需求过重
- 需要额外数据写入和维护链路

## 6. 选型

采用**方案一：结果总览专用涉疑交易接口**。

原因：

- 最符合“只在结果总览页使用”的业务边界
- 能以最短路径实现“同一流水只展示一次，但按来源切换仍可命中”
- 可以最大限度复用现有流水详情能力，同时避免污染通用流水明细查询接口

## 7. 前端设计

## 7.1 页面位置

保留在：

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

不新增路由，不调整项目详情页壳子结构。

## 7.2 交互结构

将现有“涉险交易明细”区块升级为“涉疑交易明细”：

- 区块标题：`涉疑交易明细`
- 右上角增加类型下拉，默认 `全部可疑人员类型`
- 右上角保留 `导出`
- 表格操作列保留 `查看详情`

筛选下拉固定三项：

- `全部可疑人员类型`
- `名单库命中`
- `模型规则命中`

## 7.3 表格字段

列表字段按业务语义展示，样式与“流水明细查询”页面一致：

1. `交易时间`
   - 对应 `trxDate`

2. `可疑人员`
   - 展示命中的交易对手方名称
   - 若同一流水命中多条名单库记录，优先展示与当前筛选来源一致的一条
   - `全部` 场景按“身份证/统一社会信用代码命中优先，其次名称命中”取第一条

3. `关联人`
   - 展示命中该条流水的归属对象姓名

4. `关联员工`
   - 展示员工姓名 + 工号
   - 格式：`姓名(工号)`

5. `关系`
   - 展示 `本人 / 配偶 / 其他关系`
   - 复用现有员工与关系人识别口径

6. `摘要/交易类型`
   - 主行：`userMemo`
   - 副行：`cashType`

7. `交易金额`
   - 沿用现有金额格式化和红绿配色

8. `操作`
   - `查看详情`

## 7.4 样式要求

- 表头风格、行高、金额色值、空值显示方式与“流水明细查询”保持一致
- 不保留现有占位表格中的“方向”“账号”等旧列
- 仅替换块内表格头部和数据内容，结果总览页原有卡片布局保持不变

## 8. 后端设计

## 8.1 接口设计

在结果总览控制器下新增专用接口：

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

- 路径：`GET /ccdi/project/overview/suspicious-transactions`
- 入参：
  - `projectId`
  - `suspiciousType`
  - `pageNum`
  - `pageSize`
- `suspiciousType` 固定值：
  - `ALL`
  - `NAME_LIST`
  - `MODEL_RULE`

### 2. 导出涉疑交易明细

- 路径：`POST /ccdi/project/overview/suspicious-transactions/export`
- 入参与列表一致
- 导出当前筛选下的全部结果

## 8.2 查询组织

整体查询以 `ccdi_bank_statement` 为基表，分三层处理：

### 第一层：流水归属与展示基表

基于当前结果总览和专项排查中已存在的“员工 / 关系人归属识别”逻辑，产出以下展示字段：

- `bankStatementId`
- `trxDate`
- `userMemo`
- `cashType`
- `displayAmount`
- `relatedPersonName`
- `relatedStaffName`
- `relatedStaffCode`
- `relationType`

### 第二层：模型规则命中子集

来源：

- `ccdi_bank_statement_tag_result`

条件：

- `project_id = ?`
- `rule_name like '%可疑%'`
- `bank_statement_id is not null`

输出：

- `bank_statement_id`
- `has_model_rule_hit = 1`

### 第三层：名单库命中子集

按交易对手方维度精确匹配中介库：

- 身份证
- 名称
- 统一社会信用代码

匹配范围：

- `ccdi_biz_intermediary`
- `ccdi_enterprise_base_info` 中 `risk_level = '1' and ent_source = 'INTERMEDIARY'`

输出：

- `bank_statement_id`
- `has_name_list_hit = 1`
- `suspiciousPersonName`
- `matchPriority`

其中 `matchPriority` 用于稳定挑选“可疑人员”列展示值：

- 身份证命中优先
- 统一社会信用代码命中次之
- 名称命中再次之

## 8.3 外层聚合与筛选

最终结果按 `bank_statement_id` 去重聚合，保留：

- `hasModelRuleHit`
- `hasNameListHit`
- `suspiciousPersonName`

筛选规则：

- `ALL`
  - `hasModelRuleHit = 1 OR hasNameListHit = 1`

- `NAME_LIST`
  - `hasNameListHit = 1`

- `MODEL_RULE`
  - `hasModelRuleHit = 1`

## 8.4 导出规则

导出列与页面列表列完全一致：

- 交易时间
- 可疑人员
- 关联人
- 关联员工
- 关系
- 摘要/交易类型
- 交易金额

不把详情字段直接塞入导出。

## 9. 数据前提

本功能需要能够获取交易对手方的以下字段：

- 交易对手方身份证
- 交易对手方名称
- 交易对手方统一社会信用代码

若当前流水入库链路尚未完整落这三类字段，则本次作为必要数据源一并补齐，作为涉疑交易明细功能的前置实现内容；不采用替代口径，不降级为只按名称判断。

## 10. 测试要点

### 10.1 列表查询

- 默认进入结果总览时可加载涉疑交易明细
- 三种类型切换后返回结果符合预期
- 同一条流水同时命中两类来源时只展示一条
- 切到任一命中来源时仍能查到该流水

### 10.2 展示口径

- 列头、金额配色、详情入口与“流水明细查询”一致
- `关联员工` 显示为 `姓名(工号)`
- `关系` 正确区分本人、配偶、其他关系

### 10.3 详情与导出

- `查看详情` 打开现有流水详情弹窗
- 导出结果与当前筛选口径一致
- 导出列与页面列一致

## 11. 实施拆分建议

建议后续进入实施计划时拆成前后端两份：

- 后端实施计划：
  - 新增结果总览涉疑交易 DTO / VO / Controller / Service / Mapper
  - 编写规则命中与名单库命中聚合 SQL
  - 实现导出模型
  - 如有缺失，补齐交易对手方证件号与统一社会信用代码的入库链路

- 前端实施计划：
  - 改造 `RiskDetailSection.vue`
  - 新增结果总览涉疑交易 API
  - 复用现有流水详情弹窗
  - 对齐表格样式、下拉切换和导出交互

## 12. 结论

本次采用结果总览专用涉疑交易接口，在不污染通用流水查询能力的前提下，完成“模型规则命中 + 名单库命中”的涉疑流水聚合展示，并通过流水维度去重满足“一条流水只展示一次，但切换筛选仍可命中”的核心需求。
