# 招聘平台 API 接口文档

# 招聘平台 API 接口文档

## 文档说明

本文档详细描述了招聘平台系统的RESTful API接口规范，包括请求格式、响应格式、错误码定义等。

### 文档版本

- **版本**: v3.0.0
- **更新日期**: 2026-01-25
- **作者**: Geluli
- **状态**: 生产环境可用

### 更新日志

**v3.0.0**

- ✅ 所有接口统一改为POST请求（原GET接口已废弃）
- ✅ 所有请求体（PUT/DELETE）改为POST请求
- ✅ 所有接口支持 lang 参数用于国际化
- ✅ 优化语言检测优先级机制
- ✅ 完善请求结构体定义

**v2.1.0**

- ✅ 多语言支持完善
- ✅ 数据库低耦合改造（移除外键约束）

### 基础信息

- **API Base URL**:
- **认证方式**: JWT Bearer Token
- **数据格式**: JSON
- **字符编码**: UTF-8
- **请求方法**: 所有接口统一使用 POST
- **测试验证码**: 123456 (短信和邮箱通用,临时测试用)
- **支持语言**: zh-CN, en, kk, ar

### 多语言支持

系统支持多语言国际化，所有接口响应将根据语言设置返回对应语言的错误消息和提示信息。

#### 语言设置方式

**优先级顺序：**

1. 请求头中的 Accept-Language 字段（最高优先级）
2. URL查询参数 ?lang=zh-CN
3. JSON请求体中的 lang 字段
4. 用户个人资料中的语言偏好
5. 系统默认语言（zh-CN）

#### 支持的语言列表

|语言|代码|地区|状态|
| ----------| -------| ---------------| -----------|
|中文简体|zh-CN|中国|✅ 已支持|
|英语|en|国际通用|✅ 已支持|
|哈萨克语|kk|哈萨克斯坦|✅ 已支持|
|阿拉伯语|ar|迪拜/中东地区|✅ 已支持|

### 通用约定

#### 请求头（Request Headers）

```http
Content-Type: application/json
Accept: application/json
Accept-Language: zh-CN  # 可选：zh-CN, en, kk, ar
Authorization: Bearer {jwt_token}  # 需要认证的接口

```

#### 请求参数中的 lang 字段

**所有接口都支持 **

- **类型**: string
- **必填**: 否
- **说明**: 指定响应消息的语言
- **示例值**: zh-CN, en, kk, ar
- **默认**: 用户偏好语言或系统默认语言（zh-CN）

**使用示例：**

```json
{
  "username": "testuser",
  "password": "123456",
  "lang": "en"
}

```

#### 响应格式（Response Format）

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体业务数据
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

#### 错误码（Error Codes）

|错误码|说明|HTTP状态码|
| --------| ----------------| ------------|
|200|成功|200|
|400|请求参数错误|400|
|401|未授权|401|
|403|权限不足|403|
|404|资源不存在|404|
|409|资源冲突|409|
|500|服务器内部错误|500|

## 目录

1. 认证接口
2. 验证码接口
3. 密码重置接口
4. 公共功能接口
5. 用户资料接口
6. 求职者接口
7. 简历管理接口
8. 企业认证接口
9. 企业管理接口
10. 职位管理接口
11. 人才库管理接口
12. VIP会员接口

## 认证接口（Authentication）

### 1. 用户注册

**接口地址**

**认证**

**请求参数**

```json
{
  "phone": "13800138000",         // 手机号（与邮箱二选一）
  "email": "user@example.com",    // 邮箱（与手机号二选一）
  "password": "123456",           // 密码（必填，最少6位）
  "user_type": "jobseeker",       // 用户类型（必填）：jobseeker/company/both
  "country": "CN",                // 国家代码（可选）
  "phone_code": "123456",         // 手机验证码（可选）
  "email_code": "123456",         // 邮箱验证码（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**说明**

- **必填字段**：password、user_type
- **二选一字段**：phone 和 email 至少提供一个
- **可选字段**：country、phone_code、email_code、lang
- **验证码**：开发环境下可省略，或使用默认验证码 123456
- 不传验证码：直接注册成功（开发环境）
- 传 123456：验证通过（开发环境默认验证码）
- 传其他值：需要配置短信/邮箱服务验证（生产环境）
- **user_type**：
- jobseeker：求职者
- company：企业
- both：既是求职者又是企业

**响应示例**

```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "user_id": 1,
    "username": "user_13800138000",
    "phone": "13800138000",
    "email": "user@example.com",
    "country": "CN",
    "resume_id": 1
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

**说明**

- **user_id**: 用户ID
- **username**: 系统自动生成的用户名
- **phone/email**: 手机号或邮箱（取决于注册时使用的是哪个）
- **country**: 国家代码
- **resume_id**: 简历ID（仅求职者或双重角色返回）
- 系统会自动为求职者创建一份空简历
- 后续可使用此 resume_id 来完善简历信息
- 企业用户注册时不会返回此字段

**错误响应**

```json
{
  "code": 409,
  "message": "手机号已存在",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2. 用户登录

**接口地址**

**认证**

**请求参数**

```json
{
  "account": "13800138000",       // 手机号或邮箱（必填）
  "password": "123456",           // 密码（必填）
  "current_role": "jobseeker",    // 当前角色（可选）：jobseeker/company
  "code": "123456",               // 验证码（可选）
  "code_type": "sms",             // 验证码类型（可选）：sms/email
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**说明**

- **必填字段**：account、password
- **可选字段**：current_role、code、code_type、lang
- **验证码**：开发环境下可省略，或使用默认验证码 123456
- 不传验证码：直接登录成功（开发环境）
- 传 123456：验证通过（开发环境默认验证码）
- 传其他值：需要配置短信/邮箱服务验证（生产环境）
- **current_role**：
- 如果用户只有一种角色，可省略
- 如果用户有多种角色（jobseeker和company），必须指定当前角色

**响应示例**

```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": 1,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "",
    "expires_in": 259200,
    "current_role": "jobseeker",
    "available_roles": ["jobseeker", "company"],
    "user_info": {
      "user_id": 1,
      "user_type": "both",
      "phone": "13800138000",
      "email": "user@example.com",
      "avatar": "",
      "status": "active",
      "country": "CN",
      "lang": "zh-CN",
      "is_authenticated": false,
      "vip_level": 0,
      "resume_id": 1
    }
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

**说明**

- **user_info.resume_id**: 简历ID（仅当 current_role 为 jobseeker 时返回）
- 企业角色登录时不会有此字段

### 3. 切换角色

**接口地址**

**认证**

**请求参数**

```json
{
  "role": "company",              // 目标角色（必填）：jobseeker/company
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "角色切换成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "current_role": "company"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 4. 获取用户角色列表

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "current_role": "jobseeker",
    "available_roles": [
      {
        "role": "jobseeker",
        "name": "求职者",
        "status": "active",
        "authenticated": false
      },
      {
        "role": "company",
        "name": "企业用户",
        "status": "active",
        "authenticated": false
      }
    ]
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 5. 用户登出

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "登出成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 6. 修改密码

**接口地址**

**认证**

**请求参数**

```json
{
  "old_password": "123456",       // 原密码（必填）
  "new_password": "654321",       // 新密码（必填，最少6位）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 7. 获取用户资料

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "user_id": 1,
    "username": "user_13800138000",
    "phone": "13800138000",
    "email": "user@example.com",
    "country": "CN",
    "lang": "zh-CN",
    "avatar": "",
    "status": "active"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 8. 更新用户资料

**接口地址**

**认证**

**请求参数**

```json
{
  "username": "newusername",      // 用户名（可选）
  "country": "CN",                // 国家代码（可选）
  "lang": "zh-CN",                // 语言代码（可选）
  "avatar": "http://example.com/avatar.jpg"  // 头像URL（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "资料更新成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 9. 更新用户头像

**接口地址**

**认证**

**请求类型**

**请求参数**

- avatar: 头像文件（必填，最大2MB，支持jpg/png/gif）

**响应示例**

```json
{
  "code": 200,
  "message": "头像更新成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

## 验证码接口（Verification）

### 1. 发送短信验证码

**接口地址**

**认证**

**请求参数**

```json
{
  "phone": "13800138000",         // 手机号（必填）
  "type": "register",             // 验证码类型（必填）：register/login/reset_password/change_phone
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2. 发送邮箱验证码

**接口地址**

**认证**

**请求参数**

```json
{
  "email": "user@example.com",    // 邮箱（必填）
  "type": "register",             // 验证码类型（必填）：register/login/reset_password/change_email
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 3. 验证验证码

**接口地址**

**认证**

**请求参数**

```json
{
  "phone": "13800138000",         // 手机号（与邮箱二选一）
  "email": "user@example.com",    // 邮箱（与手机号二选一）
  "code": "123456",               // 验证码（必填）
  "type": "register",             // 验证码类型（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "验证码验证成功",
  "data": {
    "valid": true
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

## 密码重置接口（Password）

### 1. 发送重置密码验证码

**接口地址**

**认证**

**请求参数**

```json
{
  "account": "13800138000",       // 手机号或邮箱（必填）
  "code_type": "sms",             // 验证码类型（必填）：sms/email
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2. 重置密码

**接口地址**

**认证**

**请求参数**

```json
{
  "account": "13800138000",       // 手机号或邮箱（必填）
  "code": "123456",               // 验证码（必填）
  "code_type": "sms",             // 验证码类型（必填）：sms/email
  "new_password": "654321",       // 新密码（必填，最少6位）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "密码重置成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

## 公共功能接口（Public Features）

### 1. 获取轮播图

**接口地址**

**认证**

**请求参数**

```json
{
  "position": "home",             // 位置（必填）：home/job/company/all
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取轮播图成功",
  "data": {
    "banners": [
      {
        "id": 1,
        "title": "新年特招",
        "image_url": "http://example.com/banner1.jpg",
        "link_url": "http://example.com/event1",
        "position": "home",
        "order": 1,
        "status": "active"
      }
    ],
    "position": "home"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2. 获取热门搜索关键词

**接口地址**

**认证**

**请求参数**

```json
{
  "type": "job",                  // 类型（必填）：job/company/all
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取热门搜索成功",
  "data": {
    "keywords": [
      "Java开发",
      "产品经理",
      "UI设计师",
      "数据分析师"
    ],
    "type": "job"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 3. 健康检查

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "服务健康",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

## 求职者接口（Jobseeker）

### 1. 获取求职者个人资料

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "user_id": 1,
    "real_name": "张三",
    "phone": "13800138000",
    "email": "user@example.com",
    "gender": "male",
    "birth_date": "1990-01-01",
    "location": "北京",
    "avatar": "http://example.com/avatar.jpg"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2. 获取投递记录

**接口地址**

**认证**

**请求参数**

```json
{
  "page": 1,                      // 页码（可选，默认1）
  "pageSize": 10,                 // 每页数量（可选，默认10）
  "status": "pending",            // 投递状态（可选）：pending/viewed/interview/rejected/hired
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**说明**

- **必填字段**：无
- **可选字段**：page、pageSize、status、lang
- **status** 状态说明：
- pending：已投递（等待查看）
- viewed：已查看（企业已查看简历）
- interview：面试中（已邀请面试）
- rejected：不合适（已拒绝）
- hired：已录用
- 不传 status：返回所有状态的投递记录

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "deliveries": [
      {
        "id": 1,
        "job_id": 100,
        "job_title": "Java开发工程师",
        "company_name": "某科技公司",
        "status": "pending",
        "created_at": "2026-01-20T10:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "pageSize": 10,
    "totalPage": 5
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2.1. 取消投递记录

**接口地址**

**认证**

**请求参数**

```json
{
  "deliveryId": 1,                // 投递记录ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "取消投递成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 3. 获取收藏列表

**接口地址**

**认证**

**请求参数**

```json
{
  "type": "job",                  // 收藏类型（可选）：job/company/all
  "page": 1,                      // 页码（可选，默认1）
  "page_size": 10,                // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "favorites": [
      {
        "id": 1,
        "type": "job",
        "target_id": 100,
        "job_title": "Java开发工程师",
        "company_name": "某科技公司"
      }
    ],
    "total": 20,
    "page": 1,
    "page_size": 10
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 4. 添加收藏

**接口地址**

**认证**

**请求参数**

```json
{
  "type": "job",                  // 收藏类型（必填）：job/company
  "targetId": 100,                // 目标ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "收藏成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 5. 取消收藏

**接口地址**

**认证**

**请求参数**

```json
{
  "favoriteId": 1,                // 收藏ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "取消收藏成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 6. 投递职位

**接口地址**

**认证**

**请求参数**

```json
{
  "jobId": 100,                   // 职位ID（必填）
  "resumeId": 1,                  // 简历ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "投递成功",
  "data": null,
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 7. 获取面试通知

**接口地址**

**认证**

**请求参数**

```json
{
  "page": 1,                      // 页码（可选，默认1）
  "pageSize": 10,                 // 每页数量（可选，默认10）
  "status": "upcoming",           // 面试状态（可选）：upcoming/completed/cancelled
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**说明**

- **必填字段**：无
- **可选字段**：page、pageSize、status、lang
- **status** 状态说明：
- upcoming：即将进行的面试
- completed：已完成的面试
- cancelled：已取消的面试
- 不传 status：返回所有状态的面试

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "interviews": [
      {
        "id": 1,
        "company_name": "某科技公司",
        "job_title": "Java开发工程师",
        "interview_time": "2026-01-30T14:00:00Z",
        "interview_type": "online",
        "location": "线上面试",
        "status": "upcoming"
      }
    ],
    "total": 5,
    "page": 1,
    "pageSize": 10,
    "totalPage": 1
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

## 简历管理接口（Resume）

**说明**

- 求职者注册时系统会自动创建一份简历
- 求职者用户登录后可通过 user_info.resume_id 获取简历ID
- 一个用户只有一份简历，无需创建多份简历
- 所有简历相关操作需要提供 resume_id 参数

### 1. 获取工作经历

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "简历创建成功",
  "data": {
    "resume_id": 1,
    "status": "pending",
    "created_at": "2026-01-25T10:30:00Z"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

**说明**

- **resume_id**: 新创建的简历ID（用于后续简历操作）
- **status**: 初始状态为 pending（待完善）
- 创建后可以通过其他接口完善简历信息（基本信息、工作经历、教育经历等）

### 3. 获取工作经历

**接口地址**

**认证**

**请求参数**

```json
{
  "resume_id": 1,                 // 简历ID（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 2. 创建工作经历

**接口地址**

**认证**

**请求参数**

```json
{
  "resumeId": 1,                  // 简历ID（必填）
  "companyName": "某科技公司",     // 公司名称（必填）
  "position": "Java开发工程师",    // 职位（必填）
  "industry": "互联网",           // 行业（可选）
  "startDate": "2020-01",         // 开始日期（必填）
  "endDate": "2022-12",           // 结束日期（可选）
  "isCurrent": false,             // 是否在职（可选）
  "location": "北京",             // 工作地点（可选）
  "description": "负责后端开发",  // 工作描述（可选）
  "salaryMin": 15000,             // 最低薪资（可选）
  "salaryMax": 20000,             // 最高薪资（可选）
  "currency": "CNY",              // 货币（可选）
  "workType": "full_time",        // 工作类型（可选）
  "displayOrder": 1,              // 显示顺序（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 3. 更新工作经历

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 工作经历ID（必填）
  "resume_id": 1,                 // 简历ID（可选）
  "company_name": "某科技公司",    // 公司名称（必填）
  "position": "Java开发工程师",    // 职位（必填）
  "industry": "互联网",           // 行业（可选）
  "start_date": "2020-01",        // 开始日期（必填）
  "end_date": "2022-12",          // 结束日期（可选）
  "is_current": false,            // 是否在职（可选）
  "location": "北京",             // 工作地点（可选）
  "description": "负责后端开发",  // 工作描述（可选）
  "salary_min": 15000,            // 最低薪资（可选）
  "salary_max": 20000,            // 最高薪资（可选）
  "currency": "CNY",              // 货币（可选）
  "work_type": "full_time",       // 工作类型（可选）
  "display_order": 1,             // 显示顺序（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 4. 删除工作经历

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 工作经历ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 5. 获取教育经历

**接口地址**

**认证**

**请求参数**

```json
{
  "resume_id": 1,                 // 简历ID（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 6. 创建教育经历

**接口地址**

**认证**

**请求参数**

```json
{
  "resumeId": 1,                  // 简历ID（必填）
  "schoolName": "北京大学",        // 学校名称（必填）
  "degree": "本科",               // 学位（必填）
  "major": "计算机科学与技术",     // 专业（必填）
  "educationLevel": "bachelor",   // 学历层次（必填）
  "startDate": "2016-09",         // 开始日期（必填）
  "endDate": "2020-06",           // 结束日期（可选）
  "isCurrent": false,             // 是否在读（可选）
  "location": "北京",             // 学校地点（可选）
  "description": "优秀毕业生",    // 描述（可选）
  "gpa": 3.8,                     // GPA（可选）
  "displayOrder": 1,              // 显示顺序（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 7. 更新教育经历

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 教育经历ID（必填）
  "resume_id": 1,                 // 简历ID（可选）
  "school_name": "北京大学",       // 学校名称（必填）
  "degree": "本科",               // 学位（必填）
  "major": "计算机科学与技术",     // 专业（必填）
  "education_level": "bachelor",   // 学历层次（必填）
  "start_date": "2016-09",        // 开始日期（必填）
  "end_date": "2020-06",          // 结束日期（可选）
  "is_current": false,            // 是否在读（可选）
  "location": "北京",             // 学校地点（可选）
  "description": "优秀毕业生",    // 描述（可选）
  "gpa": 3.8,                     // GPA（可选）
  "display_order": 1,             // 显示顺序（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 8. 删除教育经历

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 教育经历ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 9. 获取技能列表

**接口地址**

**认证**

**请求参数**

```json
{
  "resume_id": 1,                 // 简历ID（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 10. 更新技能

**接口地址**

**认证**

**请求参数**

```json
{
  "resumeId": 1,                  // 简历ID（必填）
  "skills": [                     // 技能列表（必填）
    {
      "skillName": "Java",        // 技能名称（必填）
      "skillLevel": "熟练",       // 技能等级（必填）
      "category": "编程语言",     // 分类（可选）
      "monthsOfExperience": 36,   // 经验月数（可选）
      "displayOrder": 1           // 显示顺序（可选）
    }
  ],
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 11. 获取附件列表

**接口地址**

**认证**

**请求参数**

```json
{
  "resume_id": 1,                 // 简历ID（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 12. 创建附件

**接口地址**

**认证**

**请求参数**

```json
{
  "resumeId": 1,                  // 简历ID（必填）
  "fileName": "简历.pdf",         // 文件名（必填）
  "fileUrl": "http://example.com/resume.pdf",  // 文件URL（必填）
  "fileSize": 102400,             // 文件大小（必填，字节）
  "fileType": "pdf",              // 文件类型（必填）
  "attachmentType": "resume",     // 附件类型（必填）
  "isPrimary": true,              // 是否主简历（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 13. 删除附件

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 附件ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 14. 设置主附件

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 附件ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 15. 获取简历预览

**接口地址**

**认证**

**请求参数**

```json
{
  "resume_id": 1,                 // 简历ID（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 16. 获取简历状态

**接口地址**

**认证**

**请求参数**

```json
{
  "resume_id": 1,                 // 简历ID（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 17. 求职者身份认证提交

**接口地址**

**认证**

**请求参数**

```json
{
  "userId": 1,                    // 用户ID（必填）
  "realName": "张三",             // 真实姓名（必填）
  "idCardNumber": "110101199001011234",  // 身份证号（必填）
  "idCardFront": "http://example.com/front.jpg",  // 身份证正面（必填）
  "idCardBack": "http://example.com/back.jpg",    // 身份证背面（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 18. 获取身份认证状态

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 19. 获取身份认证详情

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

## 企业认证接口（Company Authentication）

### 1. 提交企业认证

**接口地址**

**认证**

**请求参数**

```json
{
  "name": "某科技公司",            // 企业名称（必填）
  "industry": "互联网",           // 行业（必填）
  "scale": "100-499人",           // 规模（必填）
  "location": "北京",             // 地址（必填）
  "website": "http://example.com",  // 网站（可选）
  "introduction": "一家领先的互联网公司",  // 简介（必填）
  "business_license": "http://example.com/license.jpg",  // 营业执照（必填）
  "logo": "http://example.com/logo.jpg",  // Logo（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 2. 获取企业信息

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 3. 更新企业信息

**接口地址**

**认证**

**请求参数**

```json
{
  "name": "某科技公司",            // 企业名称（可选）
  "industry": "互联网",           // 行业（可选）
  "scale": "100-499人",           // 规模（可选）
  "location": "北京",             // 地址（可选）
  "website": "http://example.com",  // 网站（可选）
  "introduction": "一家领先的互联网公司",  // 简介（可选）
  "logo": "http://example.com/logo.jpg",  // Logo（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

## 企业管理接口（Company Management）

### 1. 获取企业仪表板

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "total_jobs": 50,
    "active_jobs": 30,
    "total_deliveries": 500,
    "pending_interviews": 10,
    "recent_jobs": [],
    "recent_interviews": []
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2. 获取职位列表

**接口地址**

**认证**

**请求参数**

```json
{
  "page": 1,                      // 页码（可选，默认1）
  "pageSize": 10,                 // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 3. 创建职位

**接口地址**

**认证**

**请求参数**

```json
{
  "title": "Java开发工程师",       // 职位标题（必填）
  "description": "岗位描述",       // 职位描述（必填）
  "salaryMin": 15000.0,           // 最低薪资（必填）
  "salaryMax": 20000.0,           // 最高薪资（必填）
  "salaryUnit": "month",          // 薪资单位（必填）
  "workLocation": "北京",         // 工作地点（必填）
  "workType": "full_time",        // 工作类型（必填）
  "experience": "3-5年",          // 工作经验（可选）
  "education": "本科",            // 学历要求（可选）
  "skills": ["Java", "Spring"],   // 技能要求（可选）
  "benefits": ["五险一金", "年终奖"],  // 福利待遇（可选）
  "tags": ["急招", "高薪"],       // 职位标签（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 4. 获取职位详情

**接口地址**

**认证**

**请求参数**

```json
{
  "job_id": 1,                    // 职位ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 5. 更新职位

**接口地址**

**认证**

**请求参数**

```json
{
  "job_id": 1,                    // 职位ID（必填）
  "title": "Java开发工程师",       // 职位标题（必填）
  "description": "岗位描述",       // 职位描述（必填）
  "salaryMin": 15000.0,           // 最低薪资（必填）
  "salaryMax": 20000.0,           // 最高薪资（必填）
  "salaryUnit": "month",          // 薪资单位（必填）
  "workLocation": "北京",         // 工作地点（必填）
  "workType": "full_time",        // 工作类型（必填）
  "experience": "3-5年",          // 工作经验（可选）
  "education": "本科",            // 学历要求（可选）
  "skills": ["Java", "Spring"],   // 技能要求（可选）
  "benefits": ["五险一金", "年终奖"],  // 福利待遇（可选）
  "tags": ["急招", "高薪"],       // 职位标签（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 6. 删除职位

**接口地址**

**认证**

**请求参数**

```json
{
  "job_id": 1,                    // 职位ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 7. 更新职位状态

**接口地址**

**认证**

**请求参数**

```json
{
  "job_id": 1,                    // 职位ID（必填）
  "status": "active",             // 状态（必填）：draft/active/closed/filled
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 8. 获取面试列表

**接口地址**

**认证**

**请求参数**

```json
{
  "page": 1,                      // 页码（可选，默认1）
  "page_size": 10,                // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 9. 发起面试邀约

**接口地址**

**认证**

**请求参数**

```json
{
  "userId": 1,                    // 求职者ID（必填）
  "jobId": 1,                     // 职位ID（必填）
  "interviewTime": "2026-01-30T14:00:00Z",  // 面试时间（必填）
  "interviewType": "online",      // 面试类型（必填）：online/offline
  "location": "线上面试",         // 面试地点（线下必填）
  "interviewer": "张经理",        // 面试官（可选）
  "interviewerPhone": "13800138000",  // 面试官电话（可选）
  "notes": "请准备作品集",        // 备注（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

## 公共前端接口（Public）

### 1. 获取首页内容

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 2. 搜索职位

**接口地址**

**认证**

**请求参数**

```json
{
  "keyword": "Java",              // 关键词（可选）
  "location": "北京",             // 地点（可选）
  "industry": "互联网",           // 行业（可选）
  "salary_min": 10000,            // 最低薪资（可选）
  "salary_max": 30000,            // 最高薪资（可选）
  "work_type": "full_time",       // 工作类型（可选）
  "experience": "3-5年",          // 工作经验（可选）
  "education": "本科",            // 学历（可选）
  "page": 1,                      // 页码（可选，默认1）
  "page_size": 10,                // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "jobs": [
      {
        "id": 1,
        "title": "Java开发工程师",
        "company_name": "某科技公司",
        "salary_min": 15000,
        "salary_max": 20000,
        "salary_unit": "month",
        "location": "北京",
        "work_type": "full_time"
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 10
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 3. 获取职位详情（公共）

**接口地址**

**认证**

**请求参数**

```json
{
  "job_id": 1,                    // 职位ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 4. 搜索公司

**接口地址**

**认证**

**请求参数**

```json
{
  "keyword": "科技",              // 关键词（可选）
  "industry": "互联网",           // 行业（可选）
  "location": "北京",             // 地点（可选）
  "page": 1,                      // 页码（可选，默认1）
  "page_size": 10,                // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 5. 获取公司详情

**接口地址**

**认证**

**请求参数**

```json
{
  "company_id": 1,                // 公司ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 6. 获取公司职位列表

**接口地址**

**认证**

**请求参数**

```json
{
  "company_id": 1,                // 公司ID（必填）
  "page": 1,                      // 页码（可选，默认1）
  "page_size": 10,                // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

## 人才库管理接口（Talent Pool）

### 1. 获取人才库列表

**接口地址**

**认证**

**请求参数**

```json
{
  "page": 1,                      // 页码（可选，默认1）
  "page_size": 10,                // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 2. 添加到人才库

**接口地址**

**认证**

**请求参数**

```json
{
  "jobseekerId": 1,               // 求职者ID（必填）
  "source": "delivery",           // 来源（必填）：delivery/search/manual
  "notes": "优秀的候选人",        // 备注（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 3. 更新人才库状态

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 人才库记录ID（必填）
  "status": "contacted",          // 状态（必填）：new/contacted/interviewed/hired/rejected
  "notes": "已电话沟通",          // 备注（可选）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 4. 从人才库移除

**接口地址**

**认证**

**请求参数**

```json
{
  "id": 1,                        // 人才库记录ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

## VIP会员接口（VIP）

### 1. 获取VIP套餐列表

**接口地址**

**认证**

**请求参数**

```json
{
  "type": "jobseeker",            // 套餐类型（可选）：jobseeker/company/all
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "packages": [
      {
        "id": 1,
        "name": "求职者月卡",
        "type": "jobseeker",
        "price": 9900,
        "currency": "CNY",
        "duration": 30,
        "benefits": ["查看联系方式", "优先推荐"]
      }
    ]
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 2. 获取VIP状态

**接口地址**

**认证**

**请求参数**

```json
{
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "获取数据成功",
  "data": {
    "is_vip": true,
    "level": 1,
    "expire_at": "2026-02-25T10:30:00Z",
    "remaining_days": 30
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 3. 创建订单

**接口地址**

**认证**

**请求参数**

```json
{
  "packageId": "1",               // 套餐ID（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "order_no": "20260125001",
    "amount": 9900,
    "status": "pending"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 4. 支付订单

**接口地址**

**认证**

**请求参数**

```json
{
  "orderNo": "20260125001",       // 订单号（必填）
  "paymentMethod": "alipay",      // 支付方式（必填）：alipay/wechat/balance
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

**响应示例**

```json
{
  "code": 200,
  "message": "支付成功",
  "data": {
    "order_no": "20260125001",
    "status": "paid"
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

```

### 5. 获取订单列表

**接口地址**

**认证**

**请求参数**

```json
{
  "page": 1,                      // 页码（可选，默认1）
  "page_size": 10,                // 每页数量（可选，默认10）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

### 6. 获取订单详情

**接口地址**

**认证**

**请求参数**

```json
{
  "order_no": "20260125001",       // 订单号（必填）
  "lang": "zh-CN"                 // 语言代码（可选）
}

```

## 附录

### A. 错误码完整列表

|错误码|英文标识|中文说明|
| --------| --------------------------| -------------------------------------|
|200|success|操作成功|
|400|params_invalid|请求参数错误|
|400|password_incorrect|密码错误|
|400|code_invalid|验证码错误或已过期|
|400|user_not_found|用户不存在|
|400|sms_code_invalid|短信验证码错误|
|400|email_code_invalid|邮箱验证码错误|
|400|avatar_required|头像文件必传|
|400|avatar_too_large|头像文件过大（最大2MB）|
|400|avatar_format_invalid|头像格式不支持（仅支持jpg/png/gif）|
|400|username_exists|用户名已被占用|
|400|profile_update_failed|资料更新失败|
|400|password_update_failed|密码更新失败|
|401|unauthorized|未授权，请先登录|
|403|forbidden|权限不足|
|404|user_not_found|用户不存在|
|404|job_not_found|职位不存在|
|404|company_not_found|企业不存在|
|404|resume_not_found|简历不存在|
|404|authentication_not_found|认证信息不存在|
|409|phone_exists|手机号已存在|
|409|email_exists|邮箱已存在|
|409|username_exists|用户名已存在|
|500|internal_error|服务器内部错误|
|500|get_data_failed|获取数据失败|
|500|operation_failed|操作失败|
|500|avatar_update_failed|头像更新失败|

### B. 数据字典

#### 用户类型（user_type）

|值|说明|
| -----------| ----------|
|jobseeker|求职者|
|company|企业用户|
|both|双重角色|

#### 角色类型（role）

|值|说明|
| -----------| ------------|
|jobseeker|求职者角色|
|company|企业角色|

#### 用户状态（status）

|值|说明|
| ----------| --------|
|active|活跃|
|inactive|非活跃|
|banned|已封禁|

#### 职位状态（job_status）

|值|说明|
| --------| --------|
|draft|草稿|
|active|招聘中|
|closed|已关闭|
|filled|已招满|

#### 工作类型（work_type）

|值|说明|
| ------------| --------|
|full_time|全职|
|part_time|兼职|
|contract|合同工|
|internship|实习|

#### 薪资单位（salary_unit）

|值|说明|
| -------| ------|
|month|月薪|
|year|年薪|
|hour|时薪|
|day|日薪|

#### 学历层次（education_level）

|值|说明|
| -------------| ------------|
|high_school|高中及以下|
|college|大专|
|bachelor|本科|
|master|硕士|
|phd|博士|

#### 工作经验（experience）

|值|说明|
| --------| ----------|
|entry|应届生|
|1-3年|1-3年|
|3-5年|3-5年|
|5-10年|5-10年|
|10+年|10年以上|

#### 企业规模（scale）

|值|说明|
| ------------| ------------|
|0-15人|0-15人|
|15-50人|15-50人|
|50-150人|50-150人|
|150-500人|150-500人|
|500-2000人|500-2000人|
|2000+人|2000人以上|

#### 认证状态（authentication_status）

|值|说明|
| ----------| --------|
|pending|待审核|
|approved|已通过|
|rejected|已拒绝|

#### 订单状态（order_status）

|值|说明|
| -----------| --------|
|pending|待支付|
|paid|已支付|
|cancelled|已取消|
|refunded|已退款|

#### 支付方式（payment_method）

|值|说明|
| ---------| ----------|
|alipay|支付宝|
|wechat|微信支付|
|balance|余额支付|

#### 人才库状态（talent_status）

|值|说明|
| -------------| --------|
|new|新增|
|contacted|已联系|
|interviewed|已面试|
|hired|已录用|
|rejected|已拒绝|

#### 人才库来源（talent_source）

|值|说明|
| ----------| ----------|
|delivery|投递来源|
|search|搜索来源|
|manual|手动添加|

#### 面试类型（interview_type）

|值|说明|
| ---------| ----------|
|online|线上面试|
|offline|线下面试|

### C. 联系方式

- **技术支持**: support@example.com
- **商务合作**: business@example.com
- **官方网站**:

**文档结束**