wkc
e95abccf5d
修复第387行潜在的空指针异常： - 将 f.getStaffId().equals(excel.getStaffId()) - 改为 Objects.equals(f.getStaffId(), excel.getStaffId()) - 确保当staffId为null时不会抛出NPE Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
509 lines
14 KiB
Markdown
509 lines
14 KiB
Markdown
# 员工调动导入员工ID校验功能实施计划
|
||
|
||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||
|
||
**目标:** 在员工调动导入功能中添加员工ID存在性校验，确保只导入有效员工的调动记录
|
||
|
||
**架构:** 采用批量预验证模式，在数据处理循环前执行一次批量数据库查询验证所有员工ID，不存在的记录提前标记为失败并跳过后续处理
|
||
|
||
**技术栈:** Spring Boot 3.5.8, MyBatis Plus 3.5.10, Java 17, Redis
|
||
|
||
---
|
||
|
||
## Task 1: 添加 CcdiBaseStaffMapper 依赖注入
|
||
|
||
**文件:**
|
||
- 修改: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java:48`
|
||
|
||
**Step 1: 添加依赖注入字段**
|
||
|
||
在第48行 `SysDeptMapper deptMapper` 之后添加:
|
||
|
||
```java
|
||
@Resource
|
||
private CcdiBaseStaffMapper baseStaffMapper;
|
||
```
|
||
|
||
**Step 2: 验证编译**
|
||
|
||
Run: `cd .worktrees/staff-transfer-validation && mvn clean compile -q`
|
||
Expected: 编译成功，无错误
|
||
|
||
**Step 3: 提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java
|
||
git commit -m "feat: 添加CcdiBaseStaffMapper依赖注入
|
||
|
||
为员工调动导入服务添加员工信息Mapper，用于批量验证员工ID存在性"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: 实现批量验证员工ID方法
|
||
|
||
**文件:**
|
||
- 修改: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java` (在文件末尾添加私有方法)
|
||
|
||
**Step 1: 编写批量验证方法**
|
||
|
||
在 `getImportFailures` 方法之后添加:
|
||
|
||
```java
|
||
/**
|
||
* 批量验证员工ID是否存在
|
||
*
|
||
* @param excelList Excel数据列表
|
||
* @param taskId 任务ID
|
||
* @param failures 失败记录列表（会追加验证失败的记录）
|
||
* @return 存在的员工ID集合
|
||
*/
|
||
private Set<Long> batchValidateStaffIds(List<CcdiStaffTransferExcel> excelList,
|
||
String taskId,
|
||
List<StaffTransferImportFailureVO> failures) {
|
||
// 1. 提取并去重员工ID
|
||
Set<Long> allStaffIds = excelList.stream()
|
||
.map(CcdiStaffTransferExcel::getStaffId)
|
||
.filter(Objects::nonNull)
|
||
.collect(Collectors.toSet());
|
||
|
||
if (allStaffIds.isEmpty()) {
|
||
return Collections.emptySet();
|
||
}
|
||
|
||
// 2. 批量查询存在的员工ID
|
||
ImportLogUtils.logBatchQueryStart(log, taskId, "员工ID", allStaffIds.size());
|
||
|
||
LambdaQueryWrapper<CcdiBaseStaff> wrapper = new LambdaQueryWrapper<>();
|
||
wrapper.select(CcdiBaseStaff::getStaffId)
|
||
.in(CcdiBaseStaff::getStaffId, allStaffIds);
|
||
|
||
List<CcdiBaseStaff> existingStaff = baseStaffMapper.selectList(wrapper);
|
||
Set<Long> existingStaffIds = existingStaff.stream()
|
||
.map(CcdiBaseStaff::getStaffId)
|
||
.collect(Collectors.toSet());
|
||
|
||
ImportLogUtils.logBatchQueryComplete(log, taskId, "员工ID", existingStaffIds.size());
|
||
|
||
// 3. 预验证并标记不存在的员工ID
|
||
for (int i = 0; i < excelList.size(); i++) {
|
||
CcdiStaffTransferExcel excel = excelList.get(i);
|
||
Long staffId = excel.getStaffId();
|
||
|
||
if (staffId != null && !existingStaffIds.contains(staffId)) {
|
||
StaffTransferImportFailureVO failure = new StaffTransferImportFailureVO();
|
||
BeanUtils.copyProperties(excel, failure);
|
||
failure.setErrorMessage(String.format("第%d行: 员工ID %s 不存在", i + 1, staffId));
|
||
failures.add(failure);
|
||
|
||
String keyData = String.format("员工ID=%s", staffId);
|
||
ImportLogUtils.logValidationError(log, taskId, i + 1,
|
||
failure.getErrorMessage(), keyData);
|
||
}
|
||
}
|
||
|
||
return existingStaffIds;
|
||
}
|
||
```
|
||
|
||
**Step 2: 验证编译**
|
||
|
||
Run: `cd .worktrees/staff-transfer-validation && mvn clean compile -q`
|
||
Expected: 编译成功，无错误
|
||
|
||
**Step 3: 提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java
|
||
git commit -m "feat: 实现批量验证员工ID方法
|
||
|
||
- 提取Excel中所有员工ID并去重
|
||
- 批量查询数据库中存在的员工ID
|
||
- 标记不存在的员工ID为失败记录
|
||
- 记录详细的验证日志"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: 实现检查行是否已失败方法
|
||
|
||
**文件:**
|
||
- 修改: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java` (在 batchValidateStaffIds 方法之后)
|
||
|
||
**Step 1: 编写检查方法**
|
||
|
||
```java
|
||
/**
|
||
* 检查某行数据是否已在失败列表中
|
||
*
|
||
* @param excel Excel数据
|
||
* @param failures 失败记录列表
|
||
* @return true-已失败，false-未失败
|
||
*/
|
||
private boolean isRowAlreadyFailed(CcdiStaffTransferExcel excel,
|
||
List<StaffTransferImportFailureVO> failures) {
|
||
return failures.stream()
|
||
.anyMatch(f -> f.getStaffId().equals(excel.getStaffId())
|
||
&& Objects.equals(f.getTransferDate(), excel.getTransferDate())
|
||
&& Objects.equals(f.getDeptIdBefore(), excel.getDeptIdBefore())
|
||
&& Objects.equals(f.getDeptIdAfter(), excel.getDeptIdAfter()));
|
||
}
|
||
```
|
||
|
||
**Step 2: 验证编译**
|
||
|
||
Run: `cd .worktrees/staff-transfer-validation && mvn clean compile -q`
|
||
Expected: 编译成功，无错误
|
||
|
||
**Step 3: 提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java
|
||
git commit -m "feat: 实现检查行是否已失败方法
|
||
|
||
通过比较员工ID、调动日期、调动前部门ID、调动后部门ID判断该行是否已在失败列表中"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: 在导入方法中调用批量验证
|
||
|
||
**文件:**
|
||
- 修改: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java:62-68`
|
||
|
||
**Step 1: 修改导入方法初始化部分**
|
||
|
||
在第62-68行，将:
|
||
|
||
```java
|
||
List<CcdiStaffTransfer> newRecords = new ArrayList<>();
|
||
List<StaffTransferImportFailureVO> failures = new ArrayList<>();
|
||
|
||
// 批量查询已存在的唯一键组合
|
||
ImportLogUtils.logBatchQueryStart(log, taskId, "已存在的调动记录", excelList.size());
|
||
Set<String> existingKeys = getExistingTransferKeys(excelList);
|
||
ImportLogUtils.logBatchQueryComplete(log, taskId, "调动记录", existingKeys.size());
|
||
```
|
||
|
||
修改为:
|
||
|
||
```java
|
||
List<CcdiStaffTransfer> newRecords = new ArrayList<>();
|
||
List<StaffTransferImportFailureVO> failures = new ArrayList<>();
|
||
|
||
// 批量验证员工ID是否存在
|
||
Set<Long> existingStaffIds = batchValidateStaffIds(excelList, taskId, failures);
|
||
|
||
// 批量查询已存在的唯一键组合
|
||
ImportLogUtils.logBatchQueryStart(log, taskId, "已存在的调动记录", excelList.size());
|
||
Set<String> existingKeys = getExistingTransferKeys(excelList);
|
||
ImportLogUtils.logBatchQueryComplete(log, taskId, "调动记录", existingKeys.size());
|
||
```
|
||
|
||
**Step 2: 验证编译**
|
||
|
||
Run: `cd .worktrees/staff-transfer-validation && mvn clean compile -q`
|
||
Expected: 编译成功，无错误
|
||
|
||
**Step 3: 提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java
|
||
git commit -m "feat: 在导入流程中添加员工ID批量验证
|
||
|
||
在数据处理循环前添加员工ID存在性验证阶段，提前标记无效员工ID的记录"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 5: 在主循环中跳过已失败记录
|
||
|
||
**文件:**
|
||
- 修改: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java:73-78`
|
||
|
||
**Step 1: 修改主循环开始部分**
|
||
|
||
在第73-78行，将:
|
||
|
||
```java
|
||
// 分类数据
|
||
for (int i = 0; i < excelList.size(); i++) {
|
||
CcdiStaffTransferExcel excel = excelList.get(i);
|
||
|
||
try {
|
||
```
|
||
|
||
修改为:
|
||
|
||
```java
|
||
// 分类数据
|
||
for (int i = 0; i < excelList.size(); i++) {
|
||
CcdiStaffTransferExcel excel = excelList.get(i);
|
||
|
||
// 跳过已在预验证阶段失败的记录
|
||
if (isRowAlreadyFailed(excel, failures)) {
|
||
continue;
|
||
}
|
||
|
||
try {
|
||
```
|
||
|
||
**Step 2: 验证编译**
|
||
|
||
Run: `cd .worktrees/staff-transfer-validation && mvn clean compile -q`
|
||
Expected: 编译成功，无错误
|
||
|
||
**Step 3: 提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java
|
||
git commit -m "feat: 主循环跳过已失败的记录
|
||
|
||
在数据处理循环中添加检查逻辑，跳过已在预验证阶段标记为失败的记录"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 6: 编写测试脚本
|
||
|
||
**文件:**
|
||
- 创建: `doc/test-data/staff-transfer-validation-test.http`
|
||
|
||
**Step 1: 创建HTTP测试文件**
|
||
|
||
```http
|
||
### 员工调动导入员工ID验证测试
|
||
|
||
### 1. 获取登录Token
|
||
POST http://localhost:8080/login/test
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
username=admin&password=admin123
|
||
|
||
> {%
|
||
client.global.set("token", response.body.token);
|
||
client.log("Token: " + response.body.token);
|
||
%}
|
||
|
||
### 2. 测试正常导入（所有员工ID存在）
|
||
POST http://localhost:8080/ccdi/staffTransfer/import
|
||
Authorization: Bearer {{token}}
|
||
Content-Type: multipart/form-data; boundary=boundary
|
||
|
||
--boundary
|
||
Content-Disposition: form-data; name="file"; filename="valid-staff-ids.xlsx"
|
||
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
|
||
|
||
< ./valid-staff-ids.xlsx
|
||
--boundary--
|
||
|
||
### 3. 测试部分员工ID不存在
|
||
POST http://localhost:8080/ccdi/staffTransfer/import
|
||
Authorization: Bearer {{token}}
|
||
Content-Type: multipart/form-data; boundary=boundary
|
||
|
||
--boundary
|
||
Content-Disposition: form-data; name="file"; filename="partial-invalid-ids.xlsx"
|
||
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
|
||
|
||
< ./partial-invalid-ids.xlsx
|
||
--boundary--
|
||
|
||
### 4. 测试所有员工ID不存在
|
||
POST http://localhost:8080/ccdi/staffTransfer/import
|
||
Authorization: Bearer {{token}}
|
||
Content-Type: multipart/form-data; boundary=boundary
|
||
|
||
--boundary
|
||
Content-Disposition: form-data; name="file"; filename="all-invalid-ids.xlsx"
|
||
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
|
||
|
||
< ./all-invalid-ids.xlsx
|
||
--boundary--
|
||
|
||
### 5. 查询导入状态
|
||
GET http://localhost:8080/ccdi/staffTransfer/import/status/{{taskId}}
|
||
Authorization: Bearer {{token}}
|
||
|
||
### 6. 获取失败记录
|
||
GET http://localhost:8080/ccdi/staffTransfer/import/failures/{{taskId}}
|
||
Authorization: Bearer {{token}}
|
||
```
|
||
|
||
**Step 2: 提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add doc/test-data/staff-transfer-validation-test.http
|
||
git commit -m "test: 添加员工ID验证测试脚本
|
||
|
||
包含正常导入、部分无效、全部无效等测试场景"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 7: 生成本次修改的API文档
|
||
|
||
**文件:**
|
||
- 修改: `doc/interface-doc/ccdi/staff-transfer.md` (如果文件不存在则创建)
|
||
|
||
**Step 1: 更新API文档**
|
||
|
||
在现有的员工调动导入接口文档中，添加错误情况说明:
|
||
|
||
```markdown
|
||
### 员工调动导入
|
||
|
||
**接口地址:** `POST /ccdi/staffTransfer/import`
|
||
|
||
**请求参数:**
|
||
- file: Excel文件（multipart/form-data）
|
||
|
||
**响应格式:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "导入任务已提交",
|
||
"data": {
|
||
"taskId": "uuid"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误情况:**
|
||
|
||
| 错误类型 | 错误信息示例 | 说明 |
|
||
|---------|-------------|------|
|
||
| 员工ID不存在 | 第3行: 员工ID 99999 不存在 | 该员工ID在员工信息表中不存在 |
|
||
| 员工ID为空 | 员工ID不能为空 | Excel中未填写员工ID |
|
||
| 调动类型无效 | 调动类型[xxx]无效 | 调动类型不在字典中 |
|
||
| 部门ID不存在 | 部门ID 999 不存在 | 调动前/后部门ID在部门表中不存在 |
|
||
| 记录重复 | 该员工在2026-01-01的调动记录已存在 | 数据库中已存在相同的调动记录 |
|
||
|
||
**导入状态查询:**
|
||
|
||
使用返回的 `taskId` 查询导入进度和结果。
|
||
|
||
**失败记录查询:**
|
||
|
||
导入失败或部分成功时，可通过 `taskId` 获取详细的失败记录列表。
|
||
```
|
||
|
||
**Step 2: 提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add doc/interface-doc/ccdi/staff-transfer.md
|
||
git commit -m "docs: 更新员工调动导入API文档
|
||
|
||
添加员工ID验证相关的错误情况说明"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 8: 最终验证和测试
|
||
|
||
**Step 1: 编译项目**
|
||
|
||
Run: `cd .worktrees/staff-transfer-validation && mvn clean compile -q`
|
||
Expected: 编译成功，无错误
|
||
|
||
**Step 2: 运行测试（如果有单元测试）**
|
||
|
||
Run: `cd .worktrees/staff-transfer-validation && mvn test -Dtest=*StaffTransferImport* -q`
|
||
Expected: 测试通过
|
||
|
||
**Step 3: 代码审查检查清单**
|
||
|
||
- [ ] 所有新增方法都有完整的JavaDoc注释
|
||
- [ ] 错误信息包含行号，便于用户定位
|
||
- [ ] 使用ImportLogUtils记录详细的验证日志
|
||
- [ ] 仅执行1次数据库查询批量验证所有员工ID
|
||
- [ ] 失败记录正确保存到Redis
|
||
- [ ] 与现有导入逻辑保持一致（跳过失败记录继续处理）
|
||
- [ ] 代码风格符合项目规范
|
||
- [ ] 无hardcode的字符串或数字
|
||
|
||
**Step 4: 最终提交**
|
||
|
||
```bash
|
||
cd .worktrees/staff-transfer-validation
|
||
git add -A
|
||
git commit -m "feat: 完成员工调动导入员工ID校验功能
|
||
|
||
功能实现:
|
||
- 批量预验证员工ID存在性（1次数据库查询）
|
||
- 不存在的员工ID记录错误并跳过
|
||
- 错误信息包含Excel行号
|
||
- 完整的日志记录
|
||
|
||
技术实现:
|
||
- 新增 batchValidateStaffIds() 方法
|
||
- 新增 isRowAlreadyFailed() 方法
|
||
- 修改 importTransferAsync() 主流程
|
||
- 添加 CcdiBaseStaffMapper 依赖
|
||
|
||
测试:
|
||
- 添加HTTP测试脚本
|
||
- 更新API文档
|
||
|
||
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
## 实施后任务
|
||
|
||
### 合并到主分支
|
||
|
||
**Step 1: 切换到dev_1分支**
|
||
|
||
```bash
|
||
cd D:\ccdi\ccdi
|
||
git checkout dev_1
|
||
git pull origin dev_1
|
||
```
|
||
|
||
**Step 2: 合并feature分支**
|
||
|
||
```bash
|
||
git merge feat/staff-transfer-staff-id-validation --no-ff
|
||
```
|
||
|
||
**Step 3: 推送到远程**
|
||
|
||
```bash
|
||
git push origin dev_1
|
||
```
|
||
|
||
**Step 4: 清理worktree**
|
||
|
||
```bash
|
||
git worktree remove .worktrees/staff-transfer-validation
|
||
git branch -d feat/staff-transfer-staff-id-validation
|
||
```
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### 相关文档
|
||
- 设计文档: `doc/plans/2026-02-11-staff-transfer-import-staff-id-validation-design.md`
|
||
- 员工调动接口文档: `doc/interface-doc/ccdi/staff-transfer.md`
|
||
- 导入服务代码: `ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiStaffTransferImportServiceImpl.java`
|
||
|
||
### 依赖服务
|
||
- 数据库: ccdi_intermediary_blacklist
|
||
- Redis: 用于存储导入状态和失败记录
|
||
|
||
### 测试数据准备
|
||
需要在 `doc/test-data/` 目录下准备测试Excel文件：
|
||
- `valid-staff-ids.xlsx`: 包含有效员工ID的调动记录
|
||
- `partial-invalid-ids.xlsx`: 包含部分无效员工ID的调动记录
|
||
- `all-invalid-ids.xlsx`: 所有员工ID都无效的调动记录
|