ccdi/docs/plans/2026-03-09-bank-statement-duplicate-check-design.md

# 银行流水入库重复校验设计

## 概述

在 `fetchAndSaveBankStatements(Long projectId, Integer groupId, Integer logId)` 中，
接口返回的银行流水写入 `ccdi_bank_statement` 前，需要基于业务键避免重复插入。

本次确认的重复判定键为：

- `project_id`
- `LE_ACCOUNT_NAME`
- `TRX_DATE`
- `CUSTOMER_ACCOUNT_NAME`
- `AMOUNT_BALANCE`

目标是让“重复”这条规则尽量落到数据库约束层，服务层只负责标准化输入和保留现有异步处理链路。

## 背景

当前实现位于 `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImpl.java`：

1. 分页调用流水分析接口获取流水数据
2. 将返回项转换为 `CcdiBankStatement`
3. 直接调用 `CcdiBankStatementMapper.insertBatch(...)` 批量入库

现状没有任何重复校验，重复导入同一批流水时会再次插入。

已确认的业务边界：

- 接口返回的同一批流水自身不会重复
- 如果数据库里已存在相同业务键的流水，保留原记录，不更新原数据
- 命中重复不应让整次文件处理失败

## 方案对比

### 方案一：服务层先查库再插入

做法：

- 服务层先按业务键查库
- 过滤已存在记录
- 仅插入剩余记录

优点：

- 语义直观
- 不需要调整批量插入 SQL

缺点：

- 规则只在当前入口生效，其他写入入口仍可能写入重复数据
- 并发导入时存在竞态窗口
- 代码和 SQL 都会变复杂

### 方案二：数据库唯一键 + no-op upsert

做法：

- 对业务键加唯一约束
- 批量插入改为 `INSERT ... ON DUPLICATE KEY UPDATE bank_statement_id = bank_statement_id`
- 服务层只做字段标准化

优点：

- 重复规则由数据库统一约束
- 并发下稳定
- 代码改动集中且可控

缺点：

- 需要先处理测试库中的存量重复数据
- `ON DUPLICATE KEY` 的受影响行数语义需要在本地 MySQL 实测确认

### 方案三：`INSERT IGNORE`

做法：

- 数据库加唯一键
- 批量插入改为 `INSERT IGNORE`

优点：

- SQL 最短
- 重复会被自动跳过

缺点：

- 可能连非重复键类的数据问题也一起吞掉
- 不利于保留真实错误

## 最终方案

采用方案二：`数据库唯一键 + 写入前标准化 + no-op upsert`。

核心决策：

1. 不做本次接口结果的内存去重
2. 服务层在写入前标准化去重键字段
3. 数据库侧增加唯一键统一兜底重复规则
4. 命中重复时跳过写入，不更新原有业务数据
5. 非重复键类数据库错误仍然向上抛出，并按现有流程标记 `parsed_failed`

## 详细设计

### 1. 去重键定义

重复判定使用以下五元组：

```text
project_id + LE_ACCOUNT_NAME + TRX_DATE + CUSTOMER_ACCOUNT_NAME + AMOUNT_BALANCE
```

对应到 Java 字段为：

- `projectId`
- `leAccountName`
- `trxDate`
- `customerAccountName`
- `amountBalance`

### 2. 服务层标准化

在 `CcdiFileUploadServiceImpl.fetchAndSaveBankStatements(...)` 中，
`CcdiBankStatement.fromResponse(...)` 返回实体后，补充统一标准化：

- `leAccountName = trimToEmpty(leAccountName)`
- `customerAccountName = trimToEmpty(customerAccountName)`
- `trxDate` 保持接口返回值，不额外改写格式
- `amountBalance` 保持 `BigDecimal` 语义写入数据库 `decimal(19,2)`
- `projectId` 继续由服务层显式设置

建议新增私有辅助方法，例如：

```java
private String trimToEmpty(String value) {
    return value == null ? "" : value.trim();
}

private void normalizeDedupFields(CcdiBankStatement statement) {
    statement.setLeAccountName(trimToEmpty(statement.getLeAccountName()));
    statement.setCustomerAccountName(trimToEmpty(statement.getCustomerAccountName()));
}
```

说明：

- 用户已明确 `LE_ACCOUNT_NAME` 对应 `account_name`
- `amountBalance` 的重复语义按数据库金额列处理，不引入额外字符串比较

### 3. 数据库结构调整

为保证唯一键对所有写入入口都有效，需要先把参与判重的可空字符列收紧到统一语义。

测试库迁移步骤：

1. 将 `LE_ACCOUNT_NAME`、`CUSTOMER_ACCOUNT_NAME` 的历史值做 `TRIM`
2. 将 `LE_ACCOUNT_NAME`、`CUSTOMER_ACCOUNT_NAME` 的 `NULL` 回填为空串
3. 清理已存在的重复测试数据，只保留一条
4. 新增唯一键

建议迁移脚本内容包含：

```sql
UPDATE ccdi_bank_statement
SET LE_ACCOUNT_NAME = TRIM(COALESCE(LE_ACCOUNT_NAME, '')),
    CUSTOMER_ACCOUNT_NAME = TRIM(COALESCE(CUSTOMER_ACCOUNT_NAME, ''));

ALTER TABLE ccdi_bank_statement
    MODIFY COLUMN LE_ACCOUNT_NAME varchar(240) NOT NULL DEFAULT '' COMMENT '企业账号名称',
    MODIFY COLUMN CUSTOMER_ACCOUNT_NAME varchar(240) NOT NULL DEFAULT '' COMMENT '对手方企业名称';

ALTER TABLE ccdi_bank_statement
    ADD UNIQUE KEY uk_bank_statement_dedup (
        project_id,
        LE_ACCOUNT_NAME,
        TRX_DATE,
        CUSTOMER_ACCOUNT_NAME,
        AMOUNT_BALANCE
    );
```

备注：

- `TRX_DATE`、`AMOUNT_BALANCE` 在现有表设计中已经是业务判重的一部分
- `project_id` 是当前业务写入必填字段，迁移前应确认测试库不存在空值

### 4. Mapper SQL 调整

将 `CcdiBankStatementMapper.xml` 中的批量插入改为 no-op upsert：

```sql
INSERT INTO ccdi_bank_statement (...)
VALUES
  (...),
  (...)
ON DUPLICATE KEY UPDATE
  bank_statement_id = bank_statement_id
```

语义说明：

- 新记录：正常插入
- 重复记录：命中唯一键，走 duplicate 分支，但不改任何业务字段
- 非重复键类 SQL 错误：仍然抛出异常

这样满足“保留原数据，不进行更新”的业务要求。

### 5. 日志与统计

服务层日志增加三类计数：

- 接口返回数
- 实际新增数
- 重复跳过数

这里有一个实现细节需要在本地 MySQL 上确认：

- `ON DUPLICATE KEY UPDATE bank_statement_id = bank_statement_id` 的受影响行数在 MySQL/JDBC 下是否稳定返回“新增 1、重复 0”

如果实测成立，则可以直接据此计算：

```text
重复跳过数 = 尝试写入数 - 实际新增数
```

如果实测不稳定，则需要降级为：

- 日志里保留“接口返回数 / 尝试写入数”
- 或在实现阶段补充额外计数方案

该点不影响去重正确性，只影响日志精度。

### 6. 异常处理

命中重复不应视为失败。

处理规则：

- 命中唯一键重复：不抛业务失败，继续处理后续批次
- 真实数据库错误：保持现有异常传播路径
- 外层 `processFileAsync(...)` 捕获真实异常后，仍更新上传记录为 `parsed_failed`

### 7. 文档同步

当前 `assets/对接流水分析/ccdi_bank_statement.md` 中的建表说明与现有实体/Mapper 已有漂移，
例如当前代码已经使用 `project_id`，而该文档片段未体现。

本次实现后应同步更新以下文档，避免数据库说明继续失真：

- `assets/对接流水分析/ccdi_bank_statement.md`
- 如有必要，同步 `docs/plans/2026-03-04-bank-statement-entity-design.md` 中的表结构补充说明

## 影响范围

后端代码：

- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImpl.java`
- `ccdi-project/src/main/java/com/ruoyi/ccdi/project/mapper/CcdiBankStatementMapper.java`
- `ccdi-project/src/main/resources/mapper/ccdi/project/CcdiBankStatementMapper.xml`

测试：

- `ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiFileUploadServiceImplTest.java`

数据库与文档：

- 建议新增测试库迁移脚本到 `assets/database/`
- `assets/对接流水分析/ccdi_bank_statement.md`

## 测试设计

至少覆盖以下场景：

1. 标准化逻辑：`null`、前后空格、空串输入
2. 首次导入：记录正常插入
3. 重复导入：不报错、不更新原记录
4. 混合批次：重复记录跳过，新增记录写入
5. 非唯一键类数据库异常：仍然向上抛出并触发 `parsed_failed`
6. 本地 MySQL 验证：确认 no-op upsert 的受影响行数语义

## 风险与缓解

| 风险 | 影响 | 缓解方案 |
|------|------|----------|
| 测试库已有重复数据，新增唯一键失败 | 高 | 先执行清洗脚本，再加唯一键 |
| 可空列绕过唯一键语义 | 高 | 迁移时统一回填空串并收紧为 `NOT NULL` |
| `ON DUPLICATE KEY` 受影响行数语义与预期不一致 | 中 | 实测后决定日志计数方案，不影响去重正确性 |
| 资产文档与代码继续漂移 | 中 | 实现后同步更新表结构说明 |

## 验收标准

1. 使用相同五元组重复导入时，数据库仅保留原记录
2. 重复导入不会更新原记录的任何业务字段
3. 命中重复不会导致上传记录失败
4. 非重复键类数据库错误仍会让上传记录进入 `parsed_failed`
5. 唯一键规则对后续其他写入入口同样生效