diff --git a/doc/api/ccdi-employee-import-api.md b/doc/api/ccdi-employee-import-api.md new file mode 100644 index 0000000..7bd2044 --- /dev/null +++ b/doc/api/ccdi-employee-import-api.md @@ -0,0 +1,124 @@ +# 员工信息导入相关接口文档 + +## 1. 导入员工信息(异步) + +**接口地址:** `POST /ccdi/employee/importData` + +**权限标识:** `ccdi:employee:import` + +**请求参数:** + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| file | File | 是 | Excel文件 | +| updateSupport | boolean | 否 | 是否更新已存在的数据,默认false | + +**响应示例:** + +```json +{ + "code": 200, + "msg": "导入任务已提交,正在后台处理", + "data": { + "taskId": "uuid-string", + "status": "PROCESSING", + "message": "导入任务已提交,正在后台处理" + } +} +``` + +## 2. 查询导入状态 + +**接口地址:** `GET /ccdi/employee/importStatus/{taskId}` + +**权限标识:** 无 + +**路径参数:** + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| taskId | String | 是 | 任务ID | + +**响应示例:** + +```json +{ + "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 | + +**响应示例:** + +```json +{ + "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. 失败记录只保存失败的数据,成功的数据不会存储