wkc/ccdi

Fork 0

Files

wkc 521bb80b2f 修改目录

2026-03-03 16:14:16 +08:00

14 KiB

Raw Blame History

员工实体关系管理 API 文档

概述

员工实体关系管理模块提供员工与企业关系的增删改查、批量导入导出功能。

基础路径: /ccdi/staffEnterpriseRelation

权限标识前缀: ccdi:staffEnterpriseRelation

重要更新: 自2026-02-11起,列表接口和详情接口响应中新增 personName 字段(员工姓名) ,该字段通过关联查询 ccdi_base_staff 表获取。

API 接口列表

1. 查询员工实体关系列表

接口地址: GET /ccdi/staffEnterpriseRelation/list

权限要求: ccdi:staffEnterpriseRelation:list

请求参数:

参数名	类型	必填	说明
personId	String	否	身份证号(精确查询)
socialCreditCode	String	否	统一社会信用代码(精确查询)
status	Integer	否	状态(0=无效, 1=有效)
pageNum	Integer	否	页码(默认1)
pageSize	Integer	否	每页数量(默认10)

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "personId": "110101199001011234",
      "personName": "张三",
      "relationPersonPost": "法定代表人",
      "socialCreditCode": "91110000MA000001XX",
      "enterpriseName": "某某科技有限公司",
      "status": 1,
      "remark": "补充说明",
      "dataSource": "人工导入",
      "isEmployee": 1,
      "isEmpFamily": 0,
      "isCustomer": 1,
      "isCustFamily": 0,
      "createTime": "2026-02-09 10:00:00",
      "updateTime": "2026-02-09 10:00:00",
      "createdBy": "admin",
      "updatedBy": "admin"
    }
  ],
  "total": 1
}

响应字段说明:

字段名	类型	说明
id	Long	主键ID
personId	String	身份证号
personName	String	员工姓名(通过关联查询获取)
relationPersonPost	String	关联人在企业的职务
socialCreditCode	String	统一社会信用代码
enterpriseName	String	企业名称
status	Integer	状态(0=无效, 1=有效)
remark	String	补充说明
dataSource	String	数据来源
isEmployee	Integer	是否为员工(0=否, 1=是)
isEmpFamily	Integer	是否为员工家属(0=否, 1=是)
isCustomer	Integer	是否为客户(0=否, 1=是)
isCustFamily	Integer	是否为客户家属(0=否, 1=是)
createTime	Date	创建时间
updateTime	Date	更新时间
createdBy	String	创建人
updatedBy	String	更新人

注意:

personName 字段通过 LEFT JOIN ccdi_base_staff 表获取
如果 personId 在员工信息表中不存在,personName 为 null

2. 查询员工实体关系详情

接口地址: GET /ccdi/staffEnterpriseRelation/{id}

权限要求: ccdi:staffEnterpriseRelation:query

路径参数:

参数名	类型	必填	说明
id	Long	是	主键ID

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "personId": "110101199001011234",
    "personName": "张三",
    "relationPersonPost": "法定代表人",
    "socialCreditCode": "91110000MA000001XX",
    "enterpriseName": "某某科技有限公司",
    "status": 1,
    "remark": "补充说明",
    "dataSource": "人工导入",
    "isEmployee": 1,
    "isEmpFamily": 0,
    "isCustomer": 1,
    "isCustFamily": 0,
    "createTime": "2026-02-09 10:00:00",
    "updateTime": "2026-02-09 10:00:00",
    "createdBy": "admin",
    "updatedBy": "admin"
  }
}

响应字段说明:

字段名	类型	说明
id	Long	主键ID
personId	String	身份证号
personName	String	员工姓名(通过关联查询获取)
relationPersonPost	String	关联人在企业的职务
socialCreditCode	String	统一社会信用代码
enterpriseName	String	企业名称
status	Integer	状态(0=无效, 1=有效)
remark	String	补充说明
dataSource	String	数据来源
isEmployee	Integer	是否为员工(0=否, 1=是)
isEmpFamily	Integer	是否为员工家属(0=否, 1=是)
isCustomer	Integer	是否为客户(0=否, 1=是)
isCustFamily	Integer	是否为客户家属(0=否, 1=是)
createTime	Date	创建时间
updateTime	Date	更新时间
createdBy	String	创建人
updatedBy	String	更新人

注意:

personName 字段通过 LEFT JOIN ccdi_base_staff 表获取
如果 personId 在员工信息表中不存在,personName 为 null

3. 新增员工实体关系

接口地址: POST /ccdi/staffEnterpriseRelation

权限要求: ccdi:staffEnterpriseRelation:add

请求头:

Content-Type: application/json
Authorization: Bearer {token}

请求体:

{
  "personId": "110101199001011234",
  "relationPersonPost": "法定代表人",
  "socialCreditCode": "91110000MA000001XX",
  "status": 1,
  "remark": "补充说明",
  "dataSource": "人工导入",
  "isEmployee": 1,
  "isEmpFamily": 0,
  "isCustomer": 1,
  "isCustFamily": 0
}

字段说明:

字段名	类型	必填	说明	校验规则
personId	String	是	身份证号	18位,符合国标
relationPersonPost	String	是	关联人在企业的职务	最大100字符
socialCreditCode	String	是	统一社会信用代码	18位
status	Integer	否	状态	0=无效, 1=有效, 默认1
remark	String	否	补充说明	最大500字符
dataSource	String	否	数据来源	最大100字符
isEmployee	Integer	否	是否为员工	0=否, 1=是
isEmpFamily	Integer	否	是否为员工家属	0=否, 1=是
isCustomer	Integer	否	是否为客户	0=否, 1=是
isCustFamily	Integer	否	是否为客户家属	0=否, 1=是

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

4. 修改员工实体关系

接口地址: PUT /ccdi/staffEnterpriseRelation

权限要求: ccdi:staffEnterpriseRelation:edit

请求头:

Content-Type: application/json
Authorization: Bearer {token}

请求体:

{
  "id": 1,
  "personId": "110101199001011234",
  "relationPersonPost": "法定代表人",
  "socialCreditCode": "91110000MA000001XX",
  "status": 1,
  "remark": "补充说明",
  "dataSource": "人工导入",
  "isEmployee": 1,
  "isEmpFamily": 0,
  "isCustomer": 1,
  "isCustFamily": 0
}

字段说明:

字段名	类型	必填	说明	校验规则
id	Long	是	主键ID	必填
personId	String	是	身份证号	18位,符合国标
relationPersonPost	String	是	关联人在企业的职务	最大100字符
socialCreditCode	String	是	统一社会信用代码	18位
status	Integer	否	状态	0=无效, 1=有效
remark	String	否	补充说明	最大500字符
dataSource	String	否	数据来源	最大100字符
isEmployee	Integer	否	是否为员工	0=否, 1=是
isEmpFamily	Integer	否	是否为员工家属	0=否, 1=是
isCustomer	Integer	否	是否为客户	0=否, 1=是
isCustFamily	Integer	否	是否为客户家属	0=否, 1=是

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

5. 删除员工实体关系

接口地址: DELETE /ccdi/staffEnterpriseRelation/{ids}

权限要求: ccdi:staffEnterpriseRelation:remove

路径参数:

参数名	类型	必填	说明
ids	Long[]	是	主键ID数组(多个ID用逗号分隔)

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

6. 导出员工实体关系

接口地址: POST /ccdi/staffEnterpriseRelation/export

权限要求: ccdi:staffEnterpriseRelation:export

请求参数: 与列表查询参数相同

响应: Excel文件流

7. 下载导入模板

接口地址: POST /ccdi/staffEnterpriseRelation/importTemplate

权限要求: 无

响应: Excel模板文件流(包含字典下拉框)

模板字段说明:

字段名	说明	是否必填	数据类型	示例值
身份证号	18位身份证号	是	文本	110101199001011234
关联人在企业的职务	职务名称	是	文本	法定代表人
统一社会信用代码	18位社会信用代码	是	文本	91110000MA000001XX
状态	有效/无效	否	下拉选择	有效
补充说明	备注信息	否	文本	-
数据来源	数据来源	否	文本	人工导入
是否为员工	是/否	否	下拉选择	是
是否为员工家属	是/否	否	下拉选择	否
是否为客户	是/否	否	下拉选择	是
是否为客户家属	是/否	否	下拉选择	否

8. 异步导入员工实体关系

接口地址: POST /ccdi/staffEnterpriseRelation/importData

权限要求: ccdi:staffEnterpriseRelation:import

请求头:

Content-Type: multipart/form-data
Authorization: Bearer {token}

请求参数:

参数名	类型	必填	说明
file	File	是	Excel文件

响应示例:

{
  "code": 200,
  "msg": "导入任务已提交,正在后台处理",
  "data": {
    "taskId": "import-task-20260209-100000",
    "status": "PROCESSING",
    "message": "导入任务已提交,正在后台处理"
  }
}

导入流程说明:

接口立即返回,不等待后台任务完成
通过 taskId 查询导入进度
导入完成后可查询失败记录

9. 查询导入状态

接口地址: GET /ccdi/staffEnterpriseRelation/importStatus/{taskId}

权限要求: ccdi:staffEnterpriseRelation:import

路径参数:

参数名	类型	必填	说明
taskId	String	是	任务ID(从导入接口获取)

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "taskId": "import-task-20260209-100000",
    "status": "COMPLETED",
    "totalCount": 100,
    "successCount": 95,
    "failureCount": 5,
    "message": "导入完成"
  }
}

状态说明:

PROCESSING: 处理中
COMPLETED: 已完成
FAILED: 失败

10. 查询导入失败记录

接口地址: GET /ccdi/staffEnterpriseRelation/importFailures/{taskId}

权限要求: ccdi:staffEnterpriseRelation:import

路径参数:

参数名	类型	必填	说明
taskId	String	是	任务ID

查询参数:

参数名	类型	必填	说明
pageNum	Integer	否	页码(默认1)
pageSize	Integer	否	每页数量(默认10)

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "rowNum": 5,
      "personId": "110101199001011235",
      "relationPersonPost": "法定代表人",
      "socialCreditCode": "91110000MA000001XX",
      "errorMessage": "身份证号格式不正确"
    }
  ],
  "total": 5
}

失败记录字段说明:

字段名	类型	说明
rowNum	Integer	行号
personId	String	身份证号
relationPersonPost	String	关联人在企业的职务
socialCreditCode	String	统一社会信用代码
errorMessage	String	错误信息

数据字典

状态(status)

值	说明
0	无效
1	有效

是否标志(isEmployee/isEmpFamily/isCustomer/isCustFamily)

值	说明
0	否
1	是

错误码说明

错误码	说明
200	操作成功
401	未授权,请先登录
403	无权限访问
500	服务器内部错误

更新日志

2026-02-11

新增: 在列表接口和详情接口响应中添加 personName 字段(员工姓名)
优化: 通过 LEFT JOIN ccdi_base_staff 表获取员工姓名
注意: 如果 personId 在员工信息表中不存在,personName 为 null

2026-02-09

初始版本: 完成员工实体关系管理基础功能

14 KiB Raw Blame History

员工实体关系管理 API 文档

概述

API 接口列表

1. 查询员工实体关系列表

2. 查询员工实体关系详情

3. 新增员工实体关系

4. 修改员工实体关系

5. 删除员工实体关系

6. 导出员工实体关系

7. 下载导入模板

8. 异步导入员工实体关系

9. 查询导入状态

10. 查询导入失败记录

数据字典

状态(status)

是否标志(isEmployee/isEmpFamily/isCustomer/isCustFamily)

错误码说明

更新日志

2026-02-11

2026-02-09

14 KiB

Raw Blame History