# 员工招聘信息管理 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
