docs(staff-enterprise-relation): 更新API文档,添加员工姓名字段说明
- 新增员工实体关系管理API文档 - 在列表接口和详情接口响应中添加personName字段 - 说明personName通过LEFT JOIN ccdi_base_staff表获取 - 如果personId在员工信息表中不存在,personName为null
This commit is contained in:
484
doc/api-docs/api/员工实体关系管理API文档.md
Normal file
484
doc/api-docs/api/员工实体关系管理API文档.md
Normal file
@@ -0,0 +1,484 @@
|
||||
# 员工实体关系管理 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) |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"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 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"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}
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"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=是 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 修改员工实体关系
|
||||
|
||||
**接口地址**: `PUT /ccdi/staffEnterpriseRelation`
|
||||
|
||||
**权限要求**: `ccdi:staffEnterpriseRelation:edit`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"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=是 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 删除员工实体关系
|
||||
|
||||
**接口地址**: `DELETE /ccdi/staffEnterpriseRelation/{ids}`
|
||||
|
||||
**权限要求**: `ccdi:staffEnterpriseRelation:remove`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| ids | Long[] | 是 | 主键ID数组(多个ID用逗号分隔) |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"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文件 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "导入任务已提交,正在后台处理",
|
||||
"data": {
|
||||
"taskId": "import-task-20260209-100000",
|
||||
"status": "PROCESSING",
|
||||
"message": "导入任务已提交,正在后台处理"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**导入流程说明**:
|
||||
1. 接口立即返回,不等待后台任务完成
|
||||
2. 通过 `taskId` 查询导入进度
|
||||
3. 导入完成后可查询失败记录
|
||||
|
||||
---
|
||||
|
||||
### 9. 查询导入状态
|
||||
|
||||
**接口地址**: `GET /ccdi/staffEnterpriseRelation/importStatus/{taskId}`
|
||||
|
||||
**权限要求**: `ccdi:staffEnterpriseRelation:import`
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| taskId | String | 是 | 任务ID(从导入接口获取) |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"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) |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
- 初始版本: 完成员工实体关系管理基础功能
|
||||
Reference in New Issue
Block a user