# 员工实体关系管理 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

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