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

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

## 1. 目标

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

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

## 2. 涉及范围

前端模块：

```text
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` 新增：

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

请求字段：

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

## 4. UI 设计

### 4.1 流水异常明细

位置：

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

展示方式：

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

交互：

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

提交参数：

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

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

### 4.2 对象异常明细

位置：

```text
ProjectAnalysisAbnormalTab.vue > OBJECT 卡片右上角
```

展示方式：

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

提交参数：

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

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

## 5. 确认弹窗

使用 Element UI 对话框或 `$prompt`。

推荐文案：

流水型：

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

对象型：

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

输入框：

```text
请输入排除原因
```

校验：

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 成功

提示：

```text
排除成功
```

随后刷新页面数据。

### 7.3 失败

提示后端错误信息：

```text
排除失败，请稍后重试
```

不修改当前页面数据。

### 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 环境

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

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

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

```bash
nvm use 22.22.3
```

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

### 9.2 构建验证

```bash
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. 不新增批量排除。