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

员工亲属关系导入 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)

响应示例:

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

响应示例:

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

响应示例:

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

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