ccdi/assets/api-docs/api/员工实体关系导入API文档.md

员工实体关系导入 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)

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "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:

• 新增员工身份证号存在性校验
• 优化导入性能，采用批量预验证方式