docs: 更新导入API文档，添加身份证号验证说明

- 更新员工调动记录导入API文档，添加导入验证规则说明 - 新增员工实体关系导入API文档 - 新增员工亲属关系导入API文档 - 说明新增的身份证号存在性校验功能 - 记录性能优化（批量预验证、1次遍历）
2026-02-11 17:06:36 +08:00
parent aaa6256735
commit 29b541730b
3 changed files with 388 additions and 0 deletions
--- a/doc/api-docs/api/员工亲属关系导入API文档.md
+++ b/doc/api-docs/api/员工亲属关系导入API文档.md
@@ -0,0 +1,195 @@
+# 员工亲属关系导入 API 文档
+
+## 概述
+
+员工亲属关系导入模块提供员工亲属关系的批量导入功能。
+
+**基础路径**: `/ccdi/staffFmyRelation`
+
+**权限标识前缀**: `ccdi:staffFmyRelation`
+
+**数据表**: `ccdi_cust_fmy_relation`
+
+**关联表**:
+- `ccdi_base_staff` - 员工基础信息表(通过id_card关联)
+
+---
+
+## API 接口
+
+### 1. 异步导入员工亲属关系
+
+**接口地址**: `POST /ccdi/staffFmyRelation/importData`
+
+**权限要求**: `ccdi:staffFmyRelation:import`
+
+**请求参数**: FormData
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| file | File | 是 | Excel文件 |
+| updateSupport | Boolean | 否 | 是否更新已存在的记录(默认false) |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "导入任务已提交,正在后台处理",
+  "data": {
+    "taskId": "abc123-def456-ghi789",
+    "status": "PROCESSING",
+    "message": "导入任务已提交,正在后台处理"
+  }
+}
+```
+
+**导入流程**:
+1. 上传Excel文件
+2. 后台立即返回taskId
+3. 使用taskId轮询查询导入状态
+4. 导入完成后查看失败记录(如有)
+
+**导入验证规则**:
+
+导入时会验证以下字段：
+
+| 字段名 | 验证规则 | 错误提示 |
+|--------|---------|---------|
+| 员工身份证号 | 必须在员工信息表(ccdi_base_staff)中存在 | "第N行: 身份证号[XXX]不存在于员工信息表中，请先添加员工信息" |
+| 关系类型 | 不能为空，必须在字典中存在 | "第N行: 关系类型不能为空" |
+| 关系人姓名 | 不能为空 | "第N行: 关系人姓名不能为空" |
+| 关系人证件类型 | 不能为空 | "第N行: 关系人证件类型不能为空" |
+| 关系人证件号码 | 不能为空 | "第N行: 关系人证件号码不能为空" |
+| 手机号码1 | 如果填写，必须为有效手机号 | "第N行: 手机号码1格式不正确" |
+| 手机号码2 | 如果填写，必须为有效手机号 | "第N行: 手机号码2格式不正确" |
+| 性别 | 如果填写，必须是"男"、"女"、"其他"或"M"、"F"、"O" | "第N行: 性别只能是：男、女、其他 或 M、F、O" |
+
+**性能优化**:
+- 采用批量预验证方式，仅1次数据库查询身份证号存在性
+- 批量查询已存在的身份证号+关系人证件号码组合，避免重复导入
+
+---
+
+### 2. 查询导入状态
+
+**接口地址**: `GET /ccdi/staffFmyRelation/importStatus/{taskId}`
+
+**权限要求**: `ccdi:staffFmyRelation:import`
+
+**路径参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| taskId | String | 是 | 导入任务ID |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "查询成功",
+  "data": {
+    "taskId": "abc123-def456-ghi789",
+    "status": "COMPLETED",
+    "total": 100,
+    "successCount": 95,
+    "failureCount": 5,
+    "message": "导入完成"
+  }
+}
+```
+
+**状态说明**:
+
+| 状态 | 说明 |
+|------|------|
+| PENDING | 等待处理 |
+| PROCESSING | 处理中 |
+| SUCCESS | 全部成功 |
+| PARTIAL_SUCCESS | 部分成功 |
+| FAILED | 处理失败 |
+
+---
+
+### 3. 查询导入失败记录
+
+**接口地址**: `GET /ccdi/staffFmyRelation/importFailures/{taskId}`
+
+**权限要求**: `ccdi:staffFmyRelation:import`
+
+**路径参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| taskId | String | 是 | 导入任务ID |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "查询成功",
+  "data": [
+    {
+      "personId": "999999999999999999",
+      "relationType": "父亲",
+      "relationName": "张三",
+      "relationCertType": "身份证",
+      "relationCertNo": "110101195501017890",
+      "errorMessage": "第2行: 身份证号[999999999999999999]不存在于员工信息表中，请先添加员工信息",
+      "rowNumber": 2
+    }
+  ]
+}
+```
+
+**失败记录字段说明**:
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| personId | String | 员工身份证号 |
+| relationType | String | 关系类型 |
+| relationName | String | 关系人姓名 |
+| relationCertType | String | 关系人证件类型 |
+| relationCertNo | String | 关系人证件号码 |
+| errorMessage | String | 错误信息 |
+| rowNumber | Integer | Excel行号 |
+
+---
+
+## Excel 模板字段说明
+
+| 字段名 | 是否必填 | 说明 |
+|--------|---------|------|
+| 员工身份证号 | 是 | 必须在员工信息表中存在 |
+| 关系类型 | 是 | 下拉选择字典 |
+| 关系人姓名 | 是 | 不能为空 |
+| 性别 | 否 | 下拉选择字典 |
+| 出生日期 | 否 | 日期格式 |
+| 关系人证件类型 | 是 | 下拉选择字典 |
+| 关系人证件号码 | 是 | 不能为空 |
+| 手机号码1 | 否 | 手机号格式 |
+| 手机号码2 | 否 | 手机号格式 |
+| 微信名称1-3 | 否 | 自由输入 |
+| 详细联系地址 | 否 | 自由输入 |
+| 关系详细描述 | 否 | 自由输入 |
+| 生效日期 | 否 | 日期格式 |
+| 失效日期 | 否 | 日期格式 |
+| 备注 | 否 | 自由输入 |
+
+---
+
+## 错误码说明
+
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 操作成功 |
+| 401 | 未授权 |
+| 403 | 无权限 |
+| 500 | 服务器错误 |
+
+---
+
+## 更新日志
+
+**2026-02-11**:
+- 新增员工身份证号存在性校验
+- 优化导入性能，采用批量预验证方式
--- a/doc/api-docs/api/员工实体关系导入API文档.md
+++ b/doc/api-docs/api/员工实体关系导入API文档.md
@@ -0,0 +1,178 @@
+# 员工实体关系导入 API 文档
+
+## 概述
+
+员工实体关系导入模块提供员工与企业实体关系的批量导入功能。
+
+**基础路径**: `/ccdi/staffEnterpriseRelation`
+
+**权限标识前缀**: `ccdi:staffEnterpriseRelation`
+
+**数据表**: `ccdi_cust_enterprise_relation`
+
+**关联表**:
+- `ccdi_base_staff` - 员工基础信息表(通过id_card关联)
+
+---
+
+## API 接口
+
+### 1. 异步导入员工实体关系
+
+**接口地址**: `POST /ccdi/staffEnterpriseRelation/importData`
+
+**权限要求**: `ccdi:staffEnterpriseRelation:import`
+
+**请求参数**: FormData
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| file | File | 是 | Excel文件 |
+| updateSupport | Boolean | 否 | 是否更新已存在的记录(默认false) |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "导入任务已提交,正在后台处理",
+  "data": {
+    "taskId": "abc123-def456-ghi789",
+    "status": "PROCESSING",
+    "message": "导入任务已提交,正在后台处理"
+  }
+}
+```
+
+**导入流程**:
+1. 上传Excel文件
+2. 后台立即返回taskId
+3. 使用taskId轮询查询导入状态
+4. 导入完成后查看失败记录(如有)
+
+**导入验证规则**:
+
+导入时会验证以下字段：
+
+| 字段名 | 验证规则 | 错误提示 |
+|--------|---------|---------|
+| 身份证号 | 必须在员工信息表(ccdi_base_staff)中存在 | "第N行: 身份证号[XXX]不存在于员工信息表中，请先添加员工信息" |
+| 统一社会信用代码 | 必须为18位有效统一社会信用代码 | "第N行: 统一社会信用代码格式不正确" |
+| 企业名称 | 不能为空，长度不超过200字符 | "第N行: 企业名称不能为空" 或 "企业名称长度不能超过200个字符" |
+
+**性能优化**:
+- 采用批量预验证方式，仅1次数据库查询身份证号存在性
+- 批量查询已存在的身份证号+统一社会信用代码组合，避免重复导入
+
+---
+
+### 2. 查询导入状态
+
+**接口地址**: `GET /ccdi/staffEnterpriseRelation/importStatus/{taskId}`
+
+**权限要求**: `ccdi:staffEnterpriseRelation:import`
+
+**路径参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| taskId | String | 是 | 导入任务ID |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "查询成功",
+  "data": {
+    "taskId": "abc123-def456-ghi789",
+    "status": "COMPLETED",
+    "total": 100,
+    "successCount": 95,
+    "failureCount": 5,
+    "message": "导入完成"
+  }
+}
+```
+
+**状态说明**:
+
+| 状态 | 说明 |
+|------|------|
+| PENDING | 等待处理 |
+| PROCESSING | 处理中 |
+| SUCCESS | 全部成功 |
+| PARTIAL_SUCCESS | 部分成功 |
+| FAILED | 处理失败 |
+
+---
+
+### 3. 查询导入失败记录
+
+**接口地址**: `GET /ccdi/staffEnterpriseRelation/importFailures/{taskId}`
+
+**权限要求**: `ccdi:staffEnterpriseRelation:import`
+
+**路径参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| taskId | String | 是 | 导入任务ID |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "msg": "查询成功",
+  "data": [
+    {
+      "personId": "999999999999999999",
+      "socialCreditCode": "91110000987654321X",
+      "enterpriseName": "测试企业",
+      "relationPersonPost": "总经理",
+      "errorMessage": "第2行: 身份证号[999999999999999999]不存在于员工信息表中，请先添加员工信息",
+      "rowNumber": 2
+    }
+  ]
+}
+```
+
+**失败记录字段说明**:
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| personId | String | 身份证号 |
+| socialCreditCode | String | 统一社会信用代码 |
+| enterpriseName | String | 企业名称 |
+| relationPersonPost | String | 关联人在企业的职务 |
+| errorMessage | String | 错误信息 |
+| rowNumber | Integer | Excel行号 |
+
+---
+
+## Excel 模板字段说明
+
+| 字段名 | 是否必填 | 说明 |
+|--------|---------|------|
+| 身份证号 | 是 | 必须在员工信息表中存在 |
+| 统一社会信用代码 | 是 | 18位有效统一社会信用代码 |
+| 企业名称 | 是 | 长度不超过200字符 |
+| 关联人在企业的职务 | 否 | 长度不超过100字符 |
+| 补充说明 | 否 | 备注信息 |
+
+---
+
+## 错误码说明
+
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 操作成功 |
+| 401 | 未授权 |
+| 403 | 无权限 |
+| 500 | 服务器错误 |
+
+---
+
+## 更新日志
+
+**2026-02-11**:
+- 新增员工身份证号存在性校验
+- 优化导入性能，采用批量预验证方式
--- a/doc/api-docs/api/员工调动记录管理API文档.md
+++ b/doc/api-docs/api/员工调动记录管理API文档.md
@@ -327,6 +327,21 @@
 3. 使用taskId轮询查询导入状态
 4. 导入完成后查看失败记录(如有)

+**导入验证规则**:
+
+导入时会验证以下字段：
+
+| 字段名 | 验证规则 | 错误提示 |
+|--------|---------|---------|
+| 员工ID | 必须在员工信息表(ccdi_base_staff)中存在 | "第N行: 员工ID XXX 不存在" |
+| 调动前部门ID | 必须在部门表(sys_dept)中存在 | "第N行: 调动前部门ID XXX 不存在" |
+| 调动后部门ID | 必须在部门表(sys_dept)中存在 | "第N行: 调动后部门ID XXX 不存在" |
+| 调动日期 | 必须符合yyyy-MM-dd格式 | "第N行: 调动日期格式不正确" |
+
+**性能优化**:
+- 采用批量预验证方式，仅1次数据库查询员工ID存在性
+- 从2次遍历优化为1次遍历，提升导入性能
+
 ---

 ### 9. 查询导入状态