431 lines
11 KiB
Markdown
431 lines
11 KiB
Markdown
# 员工招聘信息管理 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 条，错误如下：<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重复 |
|
||
| 招聘项目编号不能为空 | 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
|