新增开发风险明细涉疑交易明细设计文档

docs/reports/implementation/2026-03-27-development-risk-suspicious-transaction-detail-design-record.md

@@ -0,0 +1,23 @@
+# 开发风险明细涉疑交易明细设计记录
+
+## 本次改动
+
+- 新增正式设计文档：`docs/superpowers/specs/2026-03-27-development-risk-suspicious-transaction-detail-design.md`
+- 沉淀“开发风险明细 > 涉疑交易明细”功能的已确认范围、数据口径、前端展示方案、后端接口方案与测试要点
+
+## 已确认的关键口径
+
+- 同一条流水同时命中“模型规则命中”和“名单库命中”时，只展示一条
+- 切换到不同筛选类型时，该流水仍需能被正常筛出
+- `模型规则命中` 的判定口径为：`rule_name` 包含“可疑”
+- `名单库命中` 的判定口径为：交易对手方按身份证、名称、统一社会信用代码精确匹配个人中介库与实体中介库
+- `查看详情` 复用现有“流水明细查询”详情接口与弹窗
+
+## 文档落点检查
+
+- 设计文档已放入：`docs/superpowers/specs/`
+- 改动记录已放入：`docs/reports/implementation/`
+
+## 后续动作
+
+- 待用户审阅设计文档后，再进入前后端实施计划拆分阶段

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

@@ -0,0 +1,363 @@
+# 开发风险明细涉疑交易明细设计
+
+**日期**: 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. 结论
+
+本次采用结果总览专用涉疑交易接口，在不污染通用流水查询能力的前提下，完成“模型规则命中 + 名单库命中”的涉疑流水聚合展示，并通过流水维度去重满足“一条流水只展示一次，但切换筛选仍可命中”的核心需求。