From 29b541730b36413f9b91ba272d48a249556d44d2 Mon Sep 17 00:00:00 2001 From: wkc <978997012@qq.com> Date: Wed, 11 Feb 2026 17:06:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=AF=BC=E5=85=A5API?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E8=BA=AB=E4=BB=BD?= =?UTF-8?q?=E8=AF=81=E5=8F=B7=E9=AA=8C=E8=AF=81=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新员工调动记录导入API文档，添加导入验证规则说明 - 新增员工实体关系导入API文档 - 新增员工亲属关系导入API文档 - 说明新增的身份证号存在性校验功能 - 记录性能优化（批量预验证、1次遍历） --- doc/api-docs/api/员工亲属关系导入API文档.md | 195 ++++++++++++++++++++ doc/api-docs/api/员工实体关系导入API文档.md | 178 ++++++++++++++++++ doc/api-docs/api/员工调动记录管理API文档.md | 15 ++ 3 files changed, 388 insertions(+) create mode 100644 doc/api-docs/api/员工亲属关系导入API文档.md create mode 100644 doc/api-docs/api/员工实体关系导入API文档.md diff --git a/doc/api-docs/api/员工亲属关系导入API文档.md b/doc/api-docs/api/员工亲属关系导入API文档.md new file mode 100644 index 0000000..2e56b2e --- /dev/null +++ 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**: +- 新增员工身份证号存在性校验 +- 优化导入性能，采用批量预验证方式 diff --git a/doc/api-docs/api/员工实体关系导入API文档.md b/doc/api-docs/api/员工实体关系导入API文档.md new file mode 100644 index 0000000..6306b0d --- /dev/null +++ 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**: +- 新增员工身份证号存在性校验 +- 优化导入性能，采用批量预验证方式 diff --git a/doc/api-docs/api/员工调动记录管理API文档.md b/doc/api-docs/api/员工调动记录管理API文档.md index 8f1673d..a14c5a7 100644 --- 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. 查询导入状态