ccdi/doc/api/ccdi-employee-import-api.md

员工信息导入相关接口文档

1. 导入员工信息(异步)

接口地址: POST /ccdi/employee/importData

权限标识: ccdi:employee:import

请求参数:

参数名	类型	必填	说明
file	File	是	Excel文件
updateSupport	boolean	否	是否更新已存在的数据,默认false

响应示例:

{
  "code": 200,
  "msg": "导入任务已提交,正在后台处理",
  "data": {
    "taskId": "uuid-string",
    "status": "PROCESSING",
    "message": "导入任务已提交,正在后台处理"
  }
}

2. 查询导入状态

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

权限标识: 无

路径参数:

参数名	类型	必填	说明
taskId	String	是	任务ID

响应示例:

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

状态说明:

状态值	说明
PROCESSING	处理中
SUCCESS	全部成功
PARTIAL_SUCCESS	部分成功
FAILED	全部失败

3. 查询导入失败记录

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

权限标识: 无

路径参数:

参数名	类型	必填	说明
taskId	String	是	任务ID

查询参数:

参数名	类型	必填	说明
pageNum	Integer	否	页码,默认1
pageSize	Integer	否	每页条数,默认10

响应示例:

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

使用流程

1. 前端调用导入接口上传Excel文件
2. 后端立即返回taskId
3. 前端每2秒轮询查询导入状态
4. 导入完成后显示结果
5. 如有失败,显示"查看导入失败记录"按钮
6. 用户点击按钮查看失败记录详情

注意事项

1. Redis中存储的导入状态和失败记录保留7天
2. taskId如果过期或不存在,查询接口会返回错误
3. 导入是异步处理,大量数据导入不会阻塞HTTP请求
4. 失败记录只保存失败的数据,成功的数据不会存储