# 员工招聘信息管理 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": [
{
"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 查询招聘信息详情
**接口描述:** 根据招聘项目编号查询详细信息
**请求方式:** `GET`
**接口路径:** `/ccdi/staffRecruitment/{recruitId}`
**权限标识:** `ccdi:staffRecruitment:query`
**路径参数:**
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|-------|------|------|------|--------|
| recruitId | String | 是 | 招聘项目编号 | REC20250205001 |
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"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/{recruitIds}`
**权限标识:** `ccdi:staffRecruitment:remove`
**路径参数:**
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|-------|------|------|------|--------|
| recruitIds | String[] | 是 | 招聘项目编号数组,多个用逗号分隔 | REC20250205001,REC20250205002 |
**响应示例:**
```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 条，错误如下：
1、招聘项目编号 REC001 导入失败：该招聘项目编号已存在
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重复 |
| 招聘项目编号不能为空 | 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