# 员工招聘信息管理 API文档

**模块名称:** ccdi-staff-recruitment
**版本:** 1.0
**生成日期:** 2025-02-05
**基础路径:** `/ccdi/staffRecruitment`

---

## 目录

1. [查询接口](#1-查询接口)
2. [操作接口](#2-操作接口)
3. [导入导出接口](#3-导入导出接口)
4. [数据模型](#4-数据模型)
5. [错误码说明](#5-错误码说明)

---

## 1. 查询接口

### 1.1 分页查询招聘信息列表

**接口描述:** 分页查询员工招聘信息列表,支持多条件筛选

**请求方式:** `GET`

**接口路径:** `/ccdi/staffRecruitment/list`

**权限标识:** `ccdi:staffRecruitment:list`

**请求参数:**

| 参数名             | 类型      | 必填 | 说明                   | 示例值                |
|-----------------|---------|----|----------------------|--------------------|
| pageNum         | Integer | 否  | 页码，默认1               | 1                  |
| pageSize        | Integer | 否  | 每页条数，默认10            | 10                 |
| recruitName     | String  | 否  | 招聘项目名称(模糊查询)         | 2025春季招聘           |
| posName         | String  | 否  | 职位名称(模糊查询)           | 软件工程师              |
| candName        | String  | 否  | 候选人姓名(模糊查询)          | 张三                 |
| candId          | String  | 否  | 证件号码(精确查询)           | 110101199001011234 |
| admitStatus     | String  | 否  | 录用状态(精确查询)           | 录用/未录用/放弃          |
| interviewerName | String  | 否  | 面试官姓名(模糊查询,查询面试官1或2) | 李四                 |
| interviewerId   | String  | 否  | 面试官工号(精确查询,查询面试官1或2) | 10001              |

**响应示例:**

```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1002,
      "recruitId": "REC20250205001",
      "recruitName": "2025春季校园招聘",
      "posName": "Java开发工程师",
      "posCategory": "技术类",
      "posDesc": "负责后端系统开发",
      "candName": "张三",
      "candEdu": "本科",
      "candId": "110101199001011234",
      "candSchool": "清华大学",
      "candMajor": "计算机科学与技术",
      "candGrad": "202506",
      "admitStatus": "录用",
      "admitStatusDesc": "已录用该候选人",
      "interviewerName1": "李四",
      "interviewerId1": "10001",
      "interviewerName2": "王五",
      "interviewerId2": "10002",
      "createdBy": "admin",
      "createTime": "2025-02-05 10:00:00",
      "updatedBy": null,
      "updateTime": null
    }
  ],
  "total": 100
}
```

### 1.2 查询招聘信息详情

**接口描述:** 根据招聘信息主键ID查询详细信息

**请求方式:** `GET`

**接口路径:** `/ccdi/staffRecruitment/{id}`

**权限标识:** `ccdi:staffRecruitment:query`

**路径参数:**

| 参数名 | 类型   | 必填 | 说明           | 示例值 |
|------|------|----|--------------|-----|
| id   | Long | 是  | 招聘信息主键ID | 1002 |

**响应示例:**

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1002,
    "recruitId": "REC20250205001",
    "recruitName": "2025春季校园招聘",
    "posName": "Java开发工程师",
    "posCategory": "技术类",
    "posDesc": "负责后端系统开发，要求熟悉Spring Boot、MyBatis Plus等框架",
    "candName": "张三",
    "candEdu": "本科",
    "candId": "110101199001011234",
    "candSchool": "清华大学",
    "candMajor": "计算机科学与技术",
    "candGrad": "202506",
    "admitStatus": "录用",
    "admitStatusDesc": "已录用该候选人",
    "interviewerName1": "李四",
    "interviewerId1": "10001",
    "interviewerName2": "王五",
    "interviewerId2": "10002",
    "createdBy": "admin",
    "createTime": "2025-02-05 10:00:00",
    "updatedBy": null,
    "updateTime": null
  }
}
```

---

## 2. 操作接口

### 2.1 新增招聘信息

**接口描述:** 新增一条员工招聘信息

**请求方式:** `POST`

**接口路径:** `/ccdi/staffRecruitment`

**权限标识:** `ccdi:staffRecruitment:add`

**请求体:**

```json
{
  "recruitId": "REC20250205001",
  "recruitName": "2025春季校园招聘",
  "posName": "Java开发工程师",
  "posCategory": "技术类",
  "posDesc": "负责后端系统开发",
  "candName": "张三",
  "candEdu": "本科",
  "candId": "110101199001011234",
  "candSchool": "清华大学",
  "candMajor": "计算机科学与技术",
  "candGrad": "202506",
  "admitStatus": "录用",
  "interviewerName1": "李四",
  "interviewerId1": "10001",
  "interviewerName2": "王五",
  "interviewerId2": "10002"
}
```

**字段校验规则:**

| 字段          | 校验规则                        | 错误提示                  |
|-------------|-----------------------------|-----------------------|
| recruitId   | @NotBlank, @Size(max=32)    | 招聘项目编号不能为空/长度不能超过32   |
| recruitName | @NotBlank, @Size(max=100)   | 招聘项目名称不能为空/长度不能超过100  |
| posName     | @NotBlank, @Size(max=100)   | 职位名称不能为空/长度不能超过100    |
| posCategory | @NotBlank, @Size(max=50)    | 职位类别不能为空/长度不能超过50     |
| posDesc     | @NotBlank                   | 职位描述不能为空              |
| candName    | @NotBlank, @Size(max=20)    | 应聘人员姓名不能为空/长度不能超过20   |
| candEdu     | @NotBlank, @Size(max=20)    | 应聘人员学历不能为空/长度不能超过20   |
| candId      | @NotBlank, @Pattern(身份证正则)  | 证件号码不能为空/格式不正确        |
| candSchool  | @NotBlank, @Size(max=50)    | 应聘人员毕业院校不能为空/长度不能超过50 |
| candMajor   | @NotBlank, @Size(max=30)    | 应聘人员专业不能为空/长度不能超过30   |
| candGrad    | @NotBlank, @Pattern(YYYYMM) | 毕业年月不能为空/格式不正确        |
| admitStatus | @NotBlank, @EnumValid       | 录用情况不能为空/状态值不合法       |

**响应示例:**

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

### 2.2 修改招聘信息

**接口描述:** 修改已有的员工招聘信息

**请求方式:** `PUT`

**接口路径:** `/ccdi/staffRecruitment`

**权限标识:** `ccdi:staffRecruitment:edit`

**请求体:**

```json
{
  "recruitId": "REC20250205001",
  "recruitName": "2025春季校园招聘",
  "posName": "Java开发工程师",
  "posCategory": "技术类",
  "posDesc": "负责后端系统开发，负责核心模块设计",
  "candName": "张三",
  "candEdu": "本科",
  "candId": "110101199001011234",
  "candSchool": "清华大学",
  "candMajor": "计算机科学与技术",
  "candGrad": "202506",
  "admitStatus": "录用",
  "interviewerName1": "李四",
  "interviewerId1": "10001",
  "interviewerName2": "王五",
  "interviewerId2": "10002"
}
```

**响应示例:**

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

### 2.3 删除招聘信息

**接口描述:** 批量删除员工招聘信息

**请求方式:** `DELETE`

**接口路径:** `/ccdi/staffRecruitment/{ids}`

**权限标识:** `ccdi:staffRecruitment:remove`

**路径参数:**

| 参数名 | 类型   | 必填 | 说明                    | 示例值      |
|------|------|----|-----------------------|----------|
| ids  | Long[] | 是  | 招聘信息主键ID数组,多个用逗号分隔 | 1002,1003 |

**响应示例:**

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

---

## 3. 导入导出接口

### 3.1 下载导入模板

**接口描述:** 下载Excel导入模板

**请求方式:** `POST`

**接口路径:** `/ccdi/staffRecruitment/importTemplate`

**权限标识:** 无

**响应:** Excel文件流

**模板字段顺序:**

| 序号 | 字段名      | 说明        | 必填 |
|----|----------|-----------|----|
| 1  | 招聘项目编号   | 允许重复      | 是  |
| 2  | 招聘项目名称   | -         | 是  |
| 3  | 职位名称     | -         | 是  |
| 4  | 职位类别     | -         | 是  |
| 5  | 职位描述     | -         | 是  |
| 6  | 应聘人员姓名   | -         | 是  |
| 7  | 应聘人员学历   | -         | 是  |
| 8  | 应聘人员证件号码 | 身份证号      | 是  |
| 9  | 应聘人员毕业院校 | -         | 是  |
| 10 | 应聘人员专业   | -         | 是  |
| 11 | 应聘人员毕业年月 | 格式:YYYYMM | 是  |
| 12 | 录用情况     | 录用/未录用/放弃 | 是  |
| 13 | 面试官1姓名   | -         | 否  |
| 14 | 面试官1工号   | -         | 否  |
| 15 | 面试官2姓名   | -         | 否  |
| 16 | 面试官2工号   | -         | 否  |

### 3.2 批量导入

**接口描述:** 通过Excel批量导入招聘信息

**请求方式:** `POST`

**接口路径:** `/ccdi/staffRecruitment/importData?updateSupport={updateSupport}`

**权限标识:** `ccdi:staffRecruitment:import`

**请求参数:**

| 参数名           | 类型      | 必填 | 说明         | 示例值  |
|---------------|---------|----|------------|------|
| updateSupport | Boolean | 否  | 是否更新已存在的数据 | true |
| file          | File    | 是  | Excel文件    | -    |

**请求类型:** `multipart/form-data`

**响应示例 (成功):**

```json
{
  "code": 200,
  "msg": "恭喜您，数据已全部导入成功！共 10 条，数据类型：新增 8 条，更新 2 条"
}
```

**响应示例 (部分失败):**

```json
{
  "code": 500,
  "msg": "很抱歉，导入完成！成功 8 条，失败 2 条，错误如下：<br/>1、招聘项目编号 REC001 导入失败：历史工作经历匹配到多条招聘主信息<br/>2、招聘项目编号 REC002 导入失败：证件号码格式不正确"
}
```

### 3.3 导出

**接口描述:** 导出招聘信息到Excel

**请求方式:** `POST`

**接口路径:** `/ccdi/staffRecruitment/export`

**权限标识:** `ccdi:staffRecruitment:export`

**请求参数:** 与分页查询接口相同的查询条件

**响应:** Excel文件流

---

## 4. 数据模型

### 4.1 录用状态枚举 (AdmitStatus)

| 枚举值 | 说明      |
|-----|---------|
| 录用  | 已录用该候选人 |
| 未录用 | 未录用该候选人 |
| 放弃  | 候选人放弃   |

### 4.2 CcdiStaffRecruitmentVO

招聘信息返回对象,包含所有字段及状态描述。

### 4.3 CcdiStaffRecruitmentExcel

Excel导入导出对象,使用EasyExcel注解。

---

## 5. 错误码说明

| 错误码 | 说明       |
|-----|----------|
| 200 | 操作成功     |
| 400 | 参数校验失败   |
| 401 | 未授权,请先登录 |
| 403 | 无权限访问    |
| 404 | 资源不存在    |
| 409 | 数据冲突   |
| 500 | 服务器内部错误  |

### 常见业务错误

| 错误信息       | 说明                 |
|------------|--------------------|
| 历史工作经历匹配到多条招聘主信息 | 招聘项目编号重复且候选人、项目名、职位名仍无法唯一匹配从表归属 |
| 招聘项目编号不能为空 | recruitId字段为空      |
| 证件号码格式不正确  | 身份证号格式验证失败         |
| 毕业年月格式不正确  | candGrad不是YYYYMM格式 |
| 录用情况状态值不合法 | admitStatus不是枚举值之一 |

---

## 附录

### Swagger UI

访问地址: `/swagger-ui/index.html`

### 测试账号

- 用户名: admin
- 密码: admin123

### Token获取

**接口:** POST `/login`

**请求体:**

```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应:**

```json
{
  "code": 200,
  "msg": "操作成功",
  "token": "Bearer eyJhbGciOiJIUzUxMiJ9..."
}
```

---

**文档生成时间:** 2025-02-05
**文档版本:** 1.0
