From 9aee2b4cde2fb9e7faa12a2ae2ee17bcc88cd67e Mon Sep 17 00:00:00 2001
From: wkc <978997012@qq.com>
Date: Fri, 6 Feb 2026 09:53:12 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=91=98=E5=B7=A5?=
 =?UTF-8?q?=E4=BF=A1=E6=81=AF=E5=AF=BC=E5=85=A5=E6=8E=A5=E5=8F=A3=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加异步导入接口文档
- 添加导入状态查询接口文档
- 添加失败记录查询接口文档
- 说明使用流程和注意事项

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 doc/api/ccdi-employee-import-api.md | 124 ++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 doc/api/ccdi-employee-import-api.md

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. 失败记录只保存失败的数据,成功的数据不会存储