ccdi/docs/plans/frontend/2026-07-09-project-risk-exclusion-frontend-implementation.md

项目结果总览排除可疑前端实施计划

1. 目标

在项目分析详情的异常明细中提供轻量“排除可疑”操作。用户确认排除后，页面重新请求后端数据，展示过滤后的风险人员、模型预警次数、命中人数与异常明细。

本阶段不做恢复入口，不做排除记录列表。

2. 涉及范围

前端模块：

ruoyi-ui

重点文件：

1. ruoyi-ui/src/api/ccdi/projectOverview.js
2. ruoyi-ui/src/views/ccdiProject/components/detail/ProjectAnalysisAbnormalTab.vue
3. ruoyi-ui/src/views/ccdiProject/components/detail/ProjectAnalysisDialog.vue
4. ruoyi-ui/src/views/ccdiProject/components/detail/ExternalPersonDetailDialog.vue
5. ruoyi-ui/src/views/ccdiProject/components/detail/PreliminaryCheck.vue
6. ruoyi-ui/src/views/ccdiProject/components/detail/RiskPeopleSection.vue
7. ruoyi-ui/src/views/ccdiProject/components/detail/RiskModelSection.vue
8. ruoyi-ui/src/views/ccdiProject/components/detail/RiskDetailSection.vue

3. API 封装

在 projectOverview.js 新增：

export function excludeOverviewRisk(data) {
  return request({
    url: '/ccdi/project/overview/risk-exclusions',
    method: 'post',
    data
  })
}

请求字段：

{
  projectId,
  exclusionType,
  ruleCode,
  bankStatementId,
  staffIdCard,
  excludeReason
}

4. UI 设计

4.1 流水异常明细

位置：

ProjectAnalysisAbnormalTab.vue > BANK_STATEMENT 表格 > 异常标签列

展示方式：

1. 每个异常标签保持 el-tag。
2. 标签右侧增加小号文字按钮“排除可疑”。
3. 按钮与标签在同一行内，不增加大操作列。

交互：

1. 点击“排除可疑”。
2. 打开确认弹窗。
3. 用户填写排除原因。
4. 确认后调用后端接口。

提交参数：

{
  projectId,
  exclusionType: 'STATEMENT',
  ruleCode: tag.ruleCode,
  bankStatementId: row.bankStatementId,
  staffIdCard: resolvePersonIdCard(),
  excludeReason
}

其中 staffIdCard 仅作为上下文传递，后端流水型以 bankStatementId 为主。

4.2 对象异常明细

位置：

ProjectAnalysisAbnormalTab.vue > OBJECT 卡片右上角

展示方式：

1. 卡片右上角增加小号按钮“排除可疑”。
2. 样式仿照现有“加入证据库”按钮。
3. 不新增恢复按钮。

提交参数：

{
  projectId,
  exclusionType: 'OBJECT',
  ruleCode: item.ruleCode || item.modelCode,
  staffIdCard: resolvePersonIdCard(),
  excludeReason
}

实施时需要确保对象异常记录保留真实 ruleCode。如果当前对象卡片只带 modelCode，前后端需补齐 ruleCode 字段，不能用 modelCode 替代规则编码。

5. 确认弹窗

使用 Element UI 对话框或 $prompt。

推荐文案：

流水型：

确认将当前流水的“{规则名称}”标记为排除可疑吗？
该操作只影响当前流水上的这一个规则标签。

对象型：

确认将“{人员姓名}”的“{规则名称}”标记为排除可疑吗？
该操作只影响当前人员的这一个规则预警。

输入框：

请输入排除原因

校验：

1. 原因不能为空。
2. 原因长度不超过 1000。

6. 刷新策略

排除成功后不做前端本地假删除，统一通知父组件刷新。

事件链路：

1. ProjectAnalysisAbnormalTab 调用接口成功。
2. 向上 emit risk-excluded。
3. ProjectAnalysisDialog 接收后重新加载当前人员详情，并继续向上 emit。
4. PreliminaryCheck 接收后重新加载结果总览数据。
5. 子组件因 props 更新重新加载风险人员、模型卡片、命中人员与涉疑交易。

外部人员详情：

1. ExternalPersonDetailDialog 接收 risk-excluded 后重新加载外部人员流水。
2. 同时通知 PreliminaryCheck 刷新总览数据。

需要刷新的数据：

1. 风险人员列表。
2. 外部人员预警列表。
3. 风险模型卡片。
4. 风险模型命中人员。
5. 涉疑交易明细。
6. 当前弹窗异常明细。

7. 页面状态

7.1 操作中

点击确认后按钮进入 loading 或禁用状态，避免重复提交。

7.2 成功

提示：

排除成功

随后刷新页面数据。

7.3 失败

提示后端错误信息：

排除失败，请稍后重试

不修改当前页面数据。

7.4 只读项目

如果 canOperate=false，不展示“排除可疑”按钮，或展示禁用态并提示当前项目仅可查看。

8. 数据要求

前端需要从后端获取或透传以下字段：

流水标签：

1. ruleCode
2. ruleName
3. bankStatementId

对象卡片：

1. ruleCode
2. ruleName
3. modelCode
4. modelName
5. reasonDetail

人员上下文：

1. projectId
2. idNo 或 staffIdCard
3. name 或 staffName

如果对象异常卡片缺少 ruleCode，应先补齐数据映射，再展示排除按钮。

9. 测试计划

9.1 Node 环境

前端命令执行前按仓库规则：

cd ruoyi-ui
nvm use
node -v
npm -v
where node
where npm

如果 Node 14.21.3 缺少 npm.cmd，切换：

nvm use 22.22.3

并在实施记录中说明实际版本。

9.2 构建验证

npm run build:prod

9.3 浏览器验证

完成页面开发后，使用 browser-use 打开真实业务页面验证，不打开 prototype。

验证路径：

1. 登录系统。
2. 进入项目详情。
3. 打开结果总览。
4. 打开某个风险人员项目分析详情。
5. 对流水标签执行“排除可疑”。
6. 确认弹窗填写原因。
7. 验证异常明细、模型统计、风险人员数据刷新。
8. 刷新浏览器，验证排除仍生效。
9. 对对象型“年流水交易额超限”执行同样验证。

9.4 关键用例

1. 单笔流水多标签，只排除其中一个标签。
2. 对象型单预警人员，排除后人员从风险列表消失。
3. 对象型多预警人员，排除后人员保留但标签和次数减少。
4. 只读项目不显示或禁用按钮。
5. 排除原因为空时不能提交。

10. 不做事项

1. 不做恢复入口。
2. 不做排除记录管理页。
3. 不使用浏览器本地存储。
4. 不新增批量排除。