wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b8e13ce4ef9aebbd5c6fcd84160c8432fe3af9ad
ccdi/doc/requirements/plans/2026-02-06-employee-async-import-design.md
wkc 02249c402e 文件夹整理
2026-02-09 14:28:25 +08:00

18 KiB
Raw Blame History

员工信息异步导入功能设计文档

创建日期: 2026-02-06 设计者: Claude Code 状态: 已确认

一、需求概述

1.1 背景

当前员工信息导入功能为同步处理,存在以下问题:

  • 导入大量数据时前端等待时间长,用户体验差
  • 导入失败记录无法保留和查询
  • 未充分利用批量操作提升性能

1.2 目标

  • 实现异步导入,提升用户体验
  • 失败记录存储在Redis中,保留7天,支持查询
  • 新数据批量插入,已有数据使用ON DUPLICATE KEY UPDATE批量更新
  • 以前端页面按钮方式提供失败记录查询功能

1.3 核心决策

  • 唯一标识: 柜员号(employeeId)
  • Redis TTL: 7天
  • 进度反馈: 后台处理 + 完成通知
  • 失败数据格式: JSON对象列表存储

二、系统架构设计

2.1 整体架构

采用生产者-消费者模式:

前端 → Controller(立即返回) → 异步Service → Redis
            ↑                           ↓
            └──── 轮询查询状态 ←─────────┘

核心流程:

  1. 前端提交Excel文件
  2. Controller立即返回taskId,不阻塞
  3. 异步线程处理导入逻辑
  4. 结果实时写入Redis
  5. 前端轮询查询导入状态
  6. 完成后通知用户,如有失败显示查询按钮

2.2 技术选型

技术 用途 说明
Spring @Async 异步处理 独立线程池处理导入任务
Redis 结果存储 存储导入状态和失败记录,7天TTL
MyBatis Plus 批量插入 saveBatch方法批量插入新数据
自定义SQL 批量更新 INSERT ... ON DUPLICATE KEY UPDATE
ThreadPoolExecutor 线程管理 核心线程2,最大线程5

三、数据库设计

3.1 表结构修改

确保ccdi_employee表的employee_id字段有UNIQUE约束:

ALTER TABLE ccdi_employee
ADD UNIQUE KEY uk_employee_id (employee_id);

3.2 Redis数据结构

状态信息存储:

Key: import:employee:{taskId}
Type: Hash
TTL: 604800秒 (7天)

Fields:
  - status: PROCESSING | SUCCESS | PARTIAL_SUCCESS | FAILED
  - totalCount: 总记录数
  - successCount: 成功数
  - failureCount: 失败数
  - startTime: 开始时间戳
  - endTime: 结束时间戳
  - message: 状态描述

失败记录存储:

Key: import:employee:{taskId}:failures
Type: List (JSON序列化)
TTL: 604800秒 (7天)

Value: [
  {
    "employeeId": "1234567",
    "name": "张三",
    "idCard": "110101199001011234",
    "deptId": 100,
    "phone": "13800138000",
    "status": "0",
    "hireDate": "2020-01-01",
    "errorMessage": "身份证号格式错误"
  },
  ...
]

四、后端实现设计

4.1 异步配置

AsyncConfig.java:

@Configuration
@EnableAsync
public class AsyncConfig {

    @Bean("importExecutor")
    public Executor importExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(2);
        executor.setMaxPoolSize(5);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("import-async-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        executor.initialize();
        return executor;
    }
}

4.2 核心VO类

ImportResultVO (导入提交结果):

@Data
public class ImportResultVO {
    private String taskId;
    private String status;
    private String message;
}

ImportStatusVO (导入状态):

@Data
public class ImportStatusVO {
    private String taskId;
    private String status;
    private Integer totalCount;
    private Integer successCount;
    private Integer failureCount;
    private Integer progress;
    private Long startTime;
    private Long endTime;
    private String message;
}

ImportFailureVO (失败记录):

@Data
public class ImportFailureVO {
    private Long employeeId;
    private String name;
    private String idCard;
    private Long deptId;
    private String phone;
    private String status;
    private String hireDate;
    private String errorMessage;
}

4.3 Service层接口

ICcdiEmployeeService新增:

/**
 * 异步导入员工数据
 * @param excelList Excel数据列表
 * @param isUpdateSupport 是否更新已存在的数据
 * @return CompletableFuture包含导入结果
 */
CompletableFuture<ImportResultVO> importEmployeeAsync(
    List<CcdiEmployeeExcel> excelList,
    boolean isUpdateSupport
);

/**
 * 查询导入状态
 * @param taskId 任务ID
 * @return 导入状态信息
 */
ImportStatusVO getImportStatus(String taskId);

/**
 * 获取导入失败记录
 * @param taskId 任务ID
 * @return 失败记录列表
 */
List<ImportFailureVO> getImportFailures(String taskId);

4.4 核心业务逻辑

数据分类:

// 1. 批量查询已存在的柜员号
Set<Long> existingIds = employeeMapper.selectBatchIds(
    excelList.stream()
        .map(CcdiEmployeeExcel::getEmployeeId)
        .collect(Collectors.toList())
).stream()
    .map(CcdiEmployee::getEmployeeId)
    .collect(Collectors.toSet());

// 2. 分类为新数据和更新数据
List<CcdiEmployee> newRecords = new ArrayList<>();
List<CcdiEmployee> updateRecords = new ArrayList<>();

for (CcdiEmployeeExcel excel : excelList) {
    CcdiEmployee employee = convertToEntity(excel);
    if (existingIds.contains(excel.getEmployeeId())) {
        updateRecords.add(employee);
    } else {
        newRecords.add(employee);
    }
}

批量插入:

if (!newRecords.isEmpty()) {
    employeeService.saveBatch(newRecords, 500);
}

批量更新:

if (!updateRecords.isEmpty() && isUpdateSupport) {
    employeeMapper.insertOrUpdateBatch(updateRecords);
}

失败记录处理:

List<ImportFailureVO> failures = new ArrayList<>();

for (CcdiEmployeeExcel excel : excelList) {
    try {
        // 验证和导入逻辑
        validateAndImport(excel);
    } catch (Exception e) {
        ImportFailureVO failure = new ImportFailureVO();
        BeanUtils.copyProperties(excel, failure);
        failure.setErrorMessage(e.getMessage());
        failures.add(failure);
    }
}

// 存入Redis
if (!failures.isEmpty()) {
    String key = "import:employee:" + taskId + ":failures";
    redisTemplate.opsForValue().set(
        key,
        JSON.toJSONString(failures),
        7,
        TimeUnit.DAYS
    );
}

4.5 Mapper SQL

CcdiEmployeeMapper.xml:

<!-- 批量插入或更新 -->
<insert id="insertOrUpdateBatch" parameterType="java.util.List">
    INSERT INTO ccdi_employee
    (employee_id, name, dept_id, id_card, phone, hire_date, status,
     create_time, update_by, update_time, remark)
    VALUES
    <foreach collection="list" item="item" separator=",">
        (#{item.employeeId}, #{item.name}, #{item.deptId}, #{item.idCard},
         #{item.phone}, #{item.hireDate}, #{item.status}, NOW(),
         #{item.updateBy}, NOW(), #{item.remark})
    </foreach>
    ON DUPLICATE KEY UPDATE
        name = VALUES(name),
        dept_id = VALUES(dept_id),
        phone = VALUES(phone),
        hire_date = VALUES(hire_date),
        status = VALUES(status),
        update_by = VALUES(update_by),
        update_time = NOW(),
        remark = VALUES(remark)
</insert>

五、Controller层API设计

5.1 修改导入接口

接口: POST /ccdi/employee/importData

改动:

  • 改为立即返回taskId
  • 使用异步处理

响应示例:

{
  "code": 200,
  "msg": "导入任务已提交,正在后台处理",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PROCESSING",
    "message": "任务已创建"
  }
}

5.2 新增状态查询接口

接口: GET /ccdi/employee/importStatus/{taskId}

Swagger注解:

@Operation(summary = "查询员工导入状态")
@GetMapping("/importStatus/{taskId}")
public AjaxResult getImportStatus(@PathVariable String taskId)

响应示例:

{
  "code": 200,
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "SUCCESS",
    "totalCount": 100,
    "successCount": 95,
    "failureCount": 5,
    "progress": 100,
    "startTime": 1707225600000,
    "endTime": 1707225900000,
    "message": "导入完成"
  }
}

5.3 新增失败记录查询接口

接口: GET /ccdi/employee/importFailures/{taskId}

参数:

  • taskId: 任务ID (路径参数)
  • pageNum: 页码 (可选,默认1)
  • pageSize: 每页条数 (可选,默认10)

响应格式: TableDataInfo

Swagger注解:

@Operation(summary = "查询导入失败记录")
@GetMapping("/importFailures/{taskId}")
public TableDataInfo getImportFailures(
    @PathVariable String taskId,
    @RequestParam(defaultValue = "1") Integer pageNum,
    @RequestParam(defaultValue = "10") Integer pageSize
)

六、前端实现设计

6.1 API定义

api/ccdiEmployee.js新增:

// 查询导入状态
export function getImportStatus(taskId) {
  return request({
    url: '/ccdi/employee/importStatus/' + taskId,
    method: 'get'
  })
}

// 查询导入失败记录
export function getImportFailures(taskId, pageNum, pageSize) {
  return request({
    url: '/ccdi/employee/importFailures/' + taskId,
    method: 'get',
    params: { pageNum, pageSize }
  })
}

6.2 导入流程优化

修改handleFileSuccess方法:

handleFileSuccess(response, file, fileList) {
  this.upload.isUploading = false;
  this.upload.open = false;

  if (response.code === 200) {
    const taskId = response.data.taskId;

    // 显示后台处理提示
    this.$notify({
      title: '导入任务已提交',
      message: '正在后台处理中,处理完成后将通知您',
      type: 'info',
      duration: 3000
    });

    // 开始轮询检查状态
    this.startImportStatusPolling(taskId);
  } else {
    this.$modal.msgError(response.msg);
  }
}

6.3 轮询状态检查

data() {
  return {
    // ...其他data
    pollingTimer: null
  }
},

methods: {
  startImportStatusPolling(taskId) {
    this.pollingTimer = setInterval(async () => {
      const response = await getImportStatus(taskId);

      if (response.data.status !== 'PROCESSING') {
        clearInterval(this.pollingTimer);
        this.handleImportComplete(response.data);
      }
    }, 2000); // 每2秒轮询一次
  },

  handleImportComplete(statusResult) {
    if (statusResult.status === 'SUCCESS') {
      this.$notify({
        title: '导入完成',
        message: `全部成功!共导入${statusResult.totalCount}条数据`,
        type: 'success',
        duration: 5000
      });
      this.getList();
    } else if (statusResult.failureCount > 0) {
      this.$notify({
        title: '导入完成',
        message: `成功${statusResult.successCount}条,失败${statusResult.failureCount}条`,
        type: 'warning',
        duration: 5000
      });

      // 显示查看失败记录按钮
      this.showFailureButton = true;
      this.currentTaskId = statusResult.taskId;

      // 刷新列表
      this.getList();
    }
  },

  beforeDestroy() {
    // 组件销毁时清除定时器
    if (this.pollingTimer) {
      clearInterval(this.pollingTimer);
    }
  }
}

6.4 失败记录查询UI

页面按钮:

<el-row :gutter="10" class="mb8">
  <!-- 原有按钮... -->

  <el-col :span="1.5" v-if="showFailureButton">
    <el-button
      type="warning"
      icon="el-icon-warning"
      size="mini"
      @click="viewImportFailures"
    >
      查看导入失败记录 ({{ currentTaskId }})
    </el-button>
  </el-col>
</el-row>

失败记录对话框:

<el-dialog
  title="导入失败记录"
  :visible.sync="failureDialogVisible"
  width="1200px"
  append-to-body
>
  <el-table :data="failureList" v-loading="failureLoading">
    <el-table-column label="姓名" prop="name" />
    <el-table-column label="柜员号" prop="employeeId" />
    <el-table-column label="身份证号" prop="idCard" />
    <el-table-column label="电话" prop="phone" />
    <el-table-column label="失败原因" prop="errorMessage" min-width="200" />
  </el-table>

  <pagination
    v-show="failureTotal > 0"
    :total="failureTotal"
    :page.sync="failureQueryParams.pageNum"
    :limit.sync="failureQueryParams.pageSize"
    @pagination="getFailureList"
  />

  <div slot="footer">
    <el-button @click="failureDialogVisible = false">关闭</el-button>
    <el-button type="primary" @click="exportFailures">导出失败记录</el-button>
  </div>
</el-dialog>

方法实现:

data() {
  return {
    // 失败记录相关
    showFailureButton: false,
    currentTaskId: null,
    failureDialogVisible: false,
    failureList: [],
    failureLoading: false,
    failureTotal: 0,
    failureQueryParams: {
      pageNum: 1,
      pageSize: 10
    }
  }
},

methods: {
  viewImportFailures() {
    this.failureDialogVisible = true;
    this.getFailureList();
  },

  getFailureList() {
    this.failureLoading = true;
    getImportFailures(
      this.currentTaskId,
      this.failureQueryParams.pageNum,
      this.failureQueryParams.pageSize
    ).then(response => {
      this.failureList = response.rows;
      this.failureTotal = response.total;
      this.failureLoading = false;
    });
  },

  exportFailures() {
    this.download(
      'ccdi/employee/exportFailures/' + this.currentTaskId,
      {},
      `导入失败记录_${new Date().getTime()}.xlsx`
    );
  }
}

七、错误处理与边界情况

7.1 异常场景处理

场景 处理方式
导入文件格式错误 上传阶段校验,不创建任务,返回错误提示
单条数据验证失败 记录到Redis失败列表,继续处理其他数据
Redis连接失败 记录日志报警,降级处理,返回警告
线程池队列满 CallerRunsPolicy,由提交线程执行
部分成功 status=PARTIAL_SUCCESS,显示失败记录按钮
全部失败 status=FAILED,显示失败记录按钮
taskId不存在 返回404,提示任务不存在或已过期

7.2 数据一致性

  • 使用@Transactional保证批量操作原子性
  • 新数据插入和已有数据更新在同一事务
  • 任意步骤失败,整体回滚
  • Redis状态更新在事务提交后执行

7.3 幂等性

  • taskId使用UUID,全局唯一
  • 同一文件多次导入产生多个taskId
  • 支持查询历史任务状态和失败记录
  • 失败记录独立存储,互不影响

7.4 性能优化

  • 批量插入每批500条,平衡性能和内存
  • 使用ON DUPLICATE KEY UPDATE替代先查后更新
  • Redis操作使用Pipeline批量执行
  • 线程池复用,避免频繁创建销毁

八、测试策略

8.1 单元测试

  • 测试数据分类逻辑(新数据vs已有数据)
  • 测试批量插入和批量更新
  • 测试异常处理和失败记录收集
  • 测试Redis读写操作

8.2 集成测试

  • 测试完整导入流程(提交→处理→查询)
  • 测试并发导入多个文件
  • 测试Redis异常降级
  • 测试线程池满载情况

8.3 性能测试

  • 100条数据导入时间 < 2秒
  • 1000条数据导入时间 < 10秒
  • 10000条数据导入时间 < 60秒
  • 导入状态查询响应时间 < 100ms

8.4 前端测试

  • 测试轮询逻辑正确性
  • 测试通知显示和关闭
  • 测试失败记录分页查询
  • 测试组件销毁时清除定时器

九、实施检查清单

9.1 后端任务

  • 创建AsyncConfig配置类
  • 添加数据库UNIQUE约束
  • 创建VO类(ImportResultVO, ImportStatusVO, ImportFailureVO)
  • 实现Service层异步方法
  • 实现Redis状态存储逻辑
  • 实现数据分类和批量操作
  • 编写Mapper XML SQL
  • 添加Controller接口
  • 更新Swagger文档

9.2 前端任务

  • 添加API方法定义
  • 修改导入成功处理逻辑
  • 实现轮询状态检查
  • 添加查看失败记录按钮
  • 创建失败记录对话框
  • 实现分页查询失败记录
  • 添加导出失败记录功能

9.3 测试任务

  • 编写单元测试用例
  • 生成测试脚本
  • 执行集成测试
  • 进行性能测试
  • 生成测试报告

十、API文档更新

更新doc目录下的接口文档,包含:

  • 修改的导入接口说明
  • 新增的状态查询接口
  • 新增的失败记录查询接口
  • 请求/响应示例

附录

A. Redis Key命名规范

import:employee:{taskId}              # 导入状态
import:employee:{taskId}:failures     # 失败记录列表

B. 状态枚举

状态值 说明 前端行为
PROCESSING 处理中 继续轮询
SUCCESS 全部成功 显示成功通知,刷新列表
PARTIAL_SUCCESS 部分成功 显示警告通知,显示失败按钮
FAILED 全部失败 显示错误通知,显示失败按钮

C. 相关文件清单

后端:

  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/config/AsyncConfig.java
  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/domain/vo/ImportResultVO.java
  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/domain/vo/ImportStatusVO.java
  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/domain/vo/ImportFailureVO.java
  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/ICcdiEmployeeService.java
  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/service/impl/CcdiEmployeeServiceImpl.java
  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/mapper/CcdiEmployeeMapper.java
  • ruoyi-ccdi/src/main/resources/mapper/ccdi/CcdiEmployeeMapper.xml
  • ruoyi-ccdi/src/main/java/com/ruoyi/ccdi/controller/CcdiEmployeeController.java

前端:

  • ruoyi-ui/src/api/ccdiEmployee.js
  • ruoyi-ui/src/views/ccdiEmployee/index.vue

文档版本: 1.0 最后更新: 2026-02-06

Reference in New Issue View Git Blame Copy Permalink