文件夹整理

This commit is contained in:
wkc
2026-02-09 14:28:25 +08:00
parent 056d239041
commit 02249c402e
2429 changed files with 3159 additions and 239710 deletions

View File

@@ -0,0 +1,262 @@
# 员工导入Excel内双字段重复检测功能实现报告
## 功能概述
为员工导入模块添加Excel内双字段(柜员号和身份证号)重复检测功能,防止同一Excel文件中出现重复数据导入到数据库。
## 实现时间
2026-02-09
## 实现位置
- 文件: `D:\ccdi\ccdi\ruoyi-ccdi\src\main\java\com\ruoyi\ccdi\service\impl\CcdiEmployeeImportServiceImpl.java`
- 方法: `importEmployeeAsync` (第43-126行)
## 核心功能
### 1. 批量查询已存在的身份证号
在数据分类前,批量查询数据库中已存在的身份证号:
```java
Set<Long> existingIds = getExistingEmployeeIds(excelList);
Set<String> existingIdCards = getExistingIdCards(excelList);
```
**优点**:
- 减少数据库查询次数,提高性能
- 避免逐条查询导致的N+1问题
### 2. 添加Excel内处理跟踪集合
```java
Set<Long> processedEmployeeIds = new HashSet<>();
Set<String> processedIdCards = new HashSet<>();
```
**作用**:
- 跟踪Excel文件中已处理的柜员号
- 跟踪Excel文件中已处理的身份证号
- 用于检测Excel内部的重复数据
### 3. 双字段重复检测逻辑
在逐条处理时,按以下顺序检查:
```java
if (existingIds.contains(excel.getEmployeeId())) {
// 柜员号在数据库中已存在
if (isUpdateSupport) {
updateRecords.add(employee);
} else {
throw new RuntimeException("柜员号已存在且未启用更新支持");
}
} else if (processedEmployeeIds.contains(excel.getEmployeeId())) {
// 柜员号在Excel文件中重复
throw new RuntimeException(String.format("柜员号[%d]在导入文件中重复,已跳过此条记录", excel.getEmployeeId()));
} else if (StringUtils.isNotEmpty(excel.getIdCard()) &&
processedIdCards.contains(excel.getIdCard())) {
// 身份证号在Excel文件中重复
throw new RuntimeException(String.format("身份证号[%s]在导入文件中重复,已跳过此条记录", excel.getIdCard()));
} else {
// 无重复,添加到新记录
newRecords.add(employee);
// 只在成功时标记
if (excel.getEmployeeId() != null) {
processedEmployeeIds.add(excel.getEmployeeId());
}
if (StringUtils.isNotEmpty(excel.getIdCard())) {
processedIdCards.add(excel.getIdCard());
}
}
```
**检查顺序**:
1. 先检查柜员号是否在数据库中存在
2. 再检查柜员号是否在Excel文件内重复
3. 最后检查身份证号是否在Excel文件内重复
4. 只在记录成功添加到newRecords后才标记为已处理
### 4. 更新validateEmployeeData方法
**修改前**:
```java
public void validateEmployeeData(CcdiEmployeeAddDTO addDTO, Boolean isUpdateSupport, Set<Long> existingIds)
```
**修改后**:
```java
public void validateEmployeeData(CcdiEmployeeAddDTO addDTO, Boolean isUpdateSupport, Set<Long> existingIds, Set<String> existingIdCards)
```
**身份证号唯一性检查优化**:
```java
// 导入场景:如果柜员号不存在,才检查身份证号唯一性
if (!existingIds.contains(addDTO.getEmployeeId())) {
// 使用批量查询的结果检查身份证号唯一性
if (existingIdCards != null && existingIdCards.contains(addDTO.getIdCard())) {
throw new RuntimeException("该身份证号已存在");
}
}
```
**优点**:
- 使用批量查询结果,避免逐条查询
- 提高导入性能
## 技术特点
### 1. 双字段同时检测
同时检测柜员号(Long类型)和身份证号(String类型)的Excel内重复
### 2. 检查顺序合理
- 先检查数据库重复(避免无效数据处理)
- 再检查Excel内重复(防止重复导入)
- 最后标记已处理(只在成功后标记)
### 3. 空值处理
使用`StringUtils.isNotEmpty``Objects::nonNull`进行空值检查,避免空指针异常
### 4. 错误消息明确
- 柜员号重复: "柜员号[XXX]在导入文件中重复,已跳过此条记录"
- 身份证号重复: "身份证号[XXX]在导入文件中重复,已跳过此条记录"
### 5. 性能优化
- 批量查询数据库中已存在的柜员号和身份证号
- 使用HashSet进行O(1)复杂度的重复检测
- 减少数据库查询次数
## 测试场景
### 场景1: 柜员号在Excel内重复
**输入**:
```
柜员号 姓名 身份证号
1001 张三 110101199001011234
1001 李四 110101199001011235
```
**期望结果**:
- 第一条记录成功导入
- 第二条记录失败,错误信息: "柜员号[1001]在导入文件中重复,已跳过此条记录"
### 场景2: 身份证号在Excel内重复
**输入**:
```
柜员号 姓名 身份证号
1001 张三 110101199001011234
1002 李四 110101199001011234
```
**期望结果**:
- 第一条记录成功导入
- 第二条记录失败,错误信息: "身份证号[110101199001011234]在导入文件中重复,已跳过此条记录"
### 场景3: 柜员号和身份证号同时重复
**输入**:
```
柜员号 姓名 身份证号
1001 张三 110101199001011234
1001 张三 110101199001011234
```
**期望结果**:
- 第一条记录成功导入
- 第二条记录失败,错误信息: "柜员号[1001]在导入文件中重复,已跳过此条记录"
### 场景4: 正常导入(无重复)
**输入**:
```
柜员号 姓名 身份证号
1001 张三 110101199001011234
1002 李四 110101199001011235
1003 王五 110101199001011236
```
**期望结果**:
- 所有记录都成功导入
## 代码对比
### 修改前
```java
// 批量查询已存在的柜员号
Set<Long> existingIds = getExistingEmployeeIds(excelList);
// 分类数据
for (int i = 0; i < excelList.size(); i++) {
// ...
validateEmployeeData(addDTO, isUpdateSupport, existingIds);
if (existingIds.contains(excel.getEmployeeId())) {
if (isUpdateSupport) {
updateRecords.add(employee);
} else {
throw new RuntimeException("柜员号已存在且未启用更新支持");
}
} else {
newRecords.add(employee);
}
}
```
### 修改后
```java
// 批量查询已存在的柜员号和身份证号
Set<Long> existingIds = getExistingEmployeeIds(excelList);
Set<String> existingIdCards = getExistingIdCards(excelList);
// 用于跟踪Excel文件内已处理的主键
Set<Long> processedEmployeeIds = new HashSet<>();
Set<String> processedIdCards = new HashSet<>();
// 分类数据
for (int i = 0; i < excelList.size(); i++) {
// ...
validateEmployeeData(addDTO, isUpdateSupport, existingIds, existingIdCards);
if (existingIds.contains(excel.getEmployeeId())) {
if (isUpdateSupport) {
updateRecords.add(employee);
} else {
throw new RuntimeException("柜员号已存在且未启用更新支持");
}
} else if (processedEmployeeIds.contains(excel.getEmployeeId())) {
throw new RuntimeException(String.format("柜员号[%d]在导入文件中重复,已跳过此条记录", excel.getEmployeeId()));
} else if (StringUtils.isNotEmpty(excel.getIdCard()) &&
processedIdCards.contains(excel.getIdCard())) {
throw new RuntimeException(String.format("身份证号[%s]在导入文件中重复,已跳过此条记录", excel.getIdCard()));
} else {
newRecords.add(employee);
// 只在成功时标记
if (excel.getEmployeeId() != null) {
processedEmployeeIds.add(excel.getEmployeeId());
}
if (StringUtils.isNotEmpty(excel.getIdCard())) {
processedIdCards.add(excel.getIdCard());
}
}
}
```
## 参考实现
本功能参考了中介人员导入模块的双字段重复检测实现:
- 文件: `CcdiIntermediaryEntityImportServiceImpl.java`
- 关键方法: `importEntityAsync`
## 编译验证
已通过Maven编译验证,无语法错误:
```bash
mvn clean compile -DskipTests
```
编译结果: BUILD SUCCESS
## 测试脚本
测试脚本位置: `D:\ccdi\ccdi\doc\test-scripts\test_employee_duplicate_detection.py`
## 总结
本次实现成功为员工导入模块添加了Excel内双字段重复检测功能,主要改进包括:
1. **批量查询优化**: 添加`getExistingIdCards`方法批量查询已存在的身份证号
2. **双字段检测**: 同时检测柜员号和身份证号的Excel内重复
3. **性能优化**: 使用批量查询减少数据库访问次数
4. **错误处理**: 提供明确的错误提示信息
5. **代码规范**: 遵循若依框架编码规范,使用MyBatis Plus进行数据操作
该功能可以有效防止Excel文件内部的重复数据导入到数据库,提高数据质量和导入可靠性。

View File

@@ -0,0 +1,303 @@
# 员工导入Excel内双字段重复检测 - 代码流程说明
## 方法签名
```java
public void importEmployeeAsync(List<CcdiEmployeeExcel> excelList, Boolean isUpdateSupport, String taskId)
```
## 完整流程图
```
开始
├─ 1. 初始化集合
│ ├─ newRecords = new ArrayList<>() // 新增记录
│ ├─ updateRecords = new ArrayList<>() // 更新记录
│ └─ failures = new ArrayList<>() // 失败记录
├─ 2. 批量查询数据库
│ ├─ getExistingEmployeeIds(excelList)
│ │ └─ 返回: Set<Long> existingIds // 数据库中已存在的柜员号
│ │
│ └─ getExistingIdCards(excelList)
│ └─ 返回: Set<String> existingIdCards // 数据库中已存在的身份证号
├─ 3. 初始化Excel内跟踪集合
│ ├─ processedEmployeeIds = new HashSet<>() // Excel内已处理的柜员号
│ └─ processedIdCards = new HashSet<>() // Excel内已处理的身份证号
├─ 4. 遍历Excel数据
│ │
│ └─ FOR EACH excel IN excelList
│ │
│ ├─ 4.1 数据转换
│ │ ├─ addDTO = new CcdiEmployeeAddDTO()
│ │ ├─ BeanUtils.copyProperties(excel, addDTO)
│ │ └─ employee = new CcdiEmployee()
│ │ └─ BeanUtils.copyProperties(excel, employee)
│ │
│ ├─ 4.2 数据验证
│ │ └─ validateEmployeeData(addDTO, isUpdateSupport, existingIds, existingIdCards)
│ │ ├─ 验证必填字段(姓名、柜员号、部门、身份证号、电话、状态)
│ │ ├─ 验证身份证号格式
│ │ └─ 验证柜员号和身份证号唯一性
│ │
│ ├─ 4.3 重复检测与分类
│ │ │
│ │ ├─ IF existingIds.contains(excel.getEmployeeId())
│ │ │ ├─ 柜员号在数据库中已存在
│ │ │ ├─ IF isUpdateSupport
│ │ │ │ └─ updateRecords.add(employee) // 添加到更新列表
│ │ │ └─ ELSE
│ │ │ └─ throw RuntimeException("柜员号已存在且未启用更新支持")
│ │ │
│ │ ├─ ELSE IF processedEmployeeIds.contains(excel.getEmployeeId())
│ │ │ └─ throw RuntimeException("柜员号[XXX]在导入文件中重复,已跳过此条记录")
│ │ │
│ │ ├─ ELSE IF processedIdCards.contains(excel.getIdCard())
│ │ │ └─ throw RuntimeException("身份证号[XXX]在导入文件中重复,已跳过此条记录")
│ │ │
│ │ └─ ELSE
│ │ ├─ newRecords.add(employee) // 添加到新增列表
│ │ ├─ IF excel.getEmployeeId() != null
│ │ │ └─ processedEmployeeIds.add(excel.getEmployeeId()) // 标记柜员号
│ │ └─ IF StringUtils.isNotEmpty(excel.getIdCard())
│ │ └─ processedIdCards.add(excel.getIdCard()) // 标记身份证号
│ │
│ └─ 4.4 异常处理
│ └─ CATCH Exception
│ ├─ failure = new ImportFailureVO()
│ ├─ BeanUtils.copyProperties(excel, failure)
│ ├─ failure.setErrorMessage(e.getMessage())
│ └─ failures.add(failure)
├─ 5. 批量操作数据库
│ ├─ IF !newRecords.isEmpty()
│ │ └─ saveBatch(newRecords, 500) // 批量插入新数据
│ │
│ └─ IF !updateRecords.isEmpty() && isUpdateSupport
│ └─ employeeMapper.insertOrUpdateBatch(updateRecords) // 批量更新已有数据
├─ 6. 保存失败记录到Redis
│ └─ IF !failures.isEmpty()
│ └─ redisTemplate.opsForValue().set("import:employee:" + taskId + ":failures", failures, 7, TimeUnit.DAYS)
├─ 7. 生成导入结果
│ ├─ result = new ImportResult()
│ ├─ result.setTotalCount(excelList.size())
│ ├─ result.setSuccessCount(newRecords.size() + updateRecords.size())
│ └─ result.setFailureCount(failures.size())
└─ 8. 更新导入状态
└─ updateImportStatus("employee", taskId, finalStatus, result)
└─ IF result.getFailureCount() == 0
└─ finalStatus = "SUCCESS"
└─ ELSE
└─ finalStatus = "PARTIAL_SUCCESS"
结束
```
## 关键逻辑说明
### 1. 重复检测优先级
```
数据库柜员号重复 > Excel内柜员号重复 > Excel内身份证号重复
```
**原因**:
- 数据库检查优先: 避免处理已经存在且不允许更新的数据
- Excel内柜员号检查: 柜员号是主键,优先检查
- Excel内身份证号检查: 身份证号也需要唯一性
### 2. 标记时机
```
只在记录成功添加到newRecords后才标记为已处理
```
**原因**:
- 避免将验证失败的记录标记为已处理
- 确保只有成功插入数据库的记录才会占用柜员号和身份证号
- 防止因前一条记录失败导致后一条有效记录被误判为重复
### 3. 空值处理
```java
// 柜员号空值检查
if (excel.getEmployeeId() != null) {
processedEmployeeIds.add(excel.getEmployeeId());
}
// 身份证号空值检查
if (StringUtils.isNotEmpty(excel.getIdCard())) {
processedIdCards.add(excel.getIdCard());
}
```
**原因**:
- 防止空指针异常
- 确保只有有效的柜员号和身份证号才会被检查重复
### 4. 批量查询优化
```java
// 批量查询柜员号
Set<Long> existingIds = getExistingEmployeeIds(excelList);
// 批量查询身份证号
Set<String> existingIdCards = getExistingIdCards(excelList);
```
**优点**:
- 一次性查询所有需要的数据
- 避免逐条查询导致的N+1问题
- 使用HashSet实现O(1)复杂度的查找
## 错误消息说明
### 1. 柜员号在数据库中已存在
```java
"柜员号已存在且未启用更新支持"
```
### 2. 柜员号在Excel内重复
```java
String.format("柜员号[%d]在导入文件中重复,已跳过此条记录", excel.getEmployeeId())
```
**示例**: "柜员号[1001]在导入文件中重复,已跳过此条记录"
### 3. 身份证号在Excel内重复
```java
String.format("身份证号[%s]在导入文件中重复,已跳过此条记录", excel.getIdCard())
```
**示例**: "身份证号[110101199001011234]在导入文件中重复,已跳过此条记录"
## validateEmployeeData方法说明
### 方法签名
```java
public void validateEmployeeData(CcdiEmployeeAddDTO addDTO,
Boolean isUpdateSupport,
Set<Long> existingIds,
Set<String> existingIdCards)
```
### 验证流程
```
1. 验证必填字段
├─ 姓名不能为空
├─ 柜员号不能为空
├─ 所属部门不能为空
├─ 身份证号不能为空
├─ 电话不能为空
└─ 状态不能为空
2. 验证身份证号格式
└─ IdCardUtil.getErrorMessage(addDTO.getIdCard())
3. 验证唯一性
├─ IF existingIds == null (单条新增场景)
│ ├─ 检查柜员号唯一性(数据库查询)
│ └─ 检查身份证号唯一性(数据库查询)
└─ ELSE (导入场景)
├─ IF 柜员号不存在于数据库
│ └─ 检查身份证号唯一性(使用批量查询结果)
└─ ELSE (柜员号已存在,允许更新)
└─ 跳过身份证号检查(更新模式下不检查身份证号重复)
4. 验证状态
└─ 状态只能填写'0'(在职)或'1'(离职)
```
### 导入场景的身份证号唯一性检查优化
```java
// 导入场景:如果柜员号不存在,才检查身份证号唯一性
if (!existingIds.contains(addDTO.getEmployeeId())) {
// 使用批量查询的结果检查身份证号唯一性
if (existingIdCards != null && existingIdCards.contains(addDTO.getIdCard())) {
throw new RuntimeException("该身份证号已存在");
}
}
```
**优化点**:
- 使用批量查询结果`existingIdCards`,避免逐条查询数据库
- 只在柜员号不存在时才检查身份证号(因为柜员号存在时是更新模式)
## 批量查询方法说明
### getExistingEmployeeIds
```java
private Set<Long> getExistingEmployeeIds(List<CcdiEmployeeExcel> excelList) {
List<Long> employeeIds = excelList.stream()
.map(CcdiEmployeeExcel::getEmployeeId)
.filter(Objects::nonNull)
.collect(Collectors.toList());
if (employeeIds.isEmpty()) {
return Collections.emptySet();
}
List<CcdiEmployee> existingEmployees = employeeMapper.selectBatchIds(employeeIds);
return existingEmployees.stream()
.map(CcdiEmployee::getEmployeeId)
.collect(Collectors.toSet());
}
```
### getExistingIdCards
```java
private Set<String> getExistingIdCards(List<CcdiEmployeeExcel> excelList) {
List<String> idCards = excelList.stream()
.map(CcdiEmployeeExcel::getIdCard)
.filter(StringUtils::isNotEmpty)
.collect(Collectors.toList());
if (idCards.isEmpty()) {
return Collections.emptySet();
}
LambdaQueryWrapper<CcdiEmployee> wrapper = new LambdaQueryWrapper<>();
wrapper.in(CcdiEmployee::getIdCard, idCards);
List<CcdiEmployee> existingEmployees = employeeMapper.selectList(wrapper);
return existingEmployees.stream()
.map(CcdiEmployee::getIdCard)
.collect(Collectors.toSet());
}
```
**特点**:
- 使用Stream API进行数据提取和过滤
- 过滤空值,避免无效查询
- 使用MyBatis Plus的批量查询方法
- 返回Set集合,实现O(1)复杂度的查找
## 性能分析
### 时间复杂度
- 批量查询: O(n), n为Excel记录数
- 重复检测: O(1), 使用HashSet
- 总体复杂度: O(n)
### 空间复杂度
- existingIds: O(m), m为数据库中已存在的柜员号数量
- existingIdCards: O(k), k为数据库中已存在的身份证号数量
- processedEmployeeIds: O(n), n为Excel记录数
- processedIdCards: O(n), n为Excel记录数
- 总体空间复杂度: O(m + k + n)
### 数据库查询次数
- 修改前: 1次(批量查询柜员号) + n次(逐条查询身份证号) = O(n)
- 修改后: 2次(批量查询柜员号 + 批量查询身份证号) = O(1)
**性能提升**: 减少n-1次数据库查询
## 总结
本实现通过以下技术手段实现了Excel内双字段重复检测:
1. 批量查询优化,减少数据库访问
2. 使用HashSet进行O(1)复杂度的重复检测
3. 合理的检查顺序和标记时机
4. 完善的空值处理和错误提示
5. 遵循若依框架编码规范,使用MyBatis Plus进行数据操作