ccdi/docs/superpowers/specs/2026-03-27-development-risk-suspicious-transaction-detail-design.md

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

日期: 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. 结论

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