# 多语言招聘网站API接口文档

# 多语言招聘网站API接口文档

## 1. 接口设计概述

### 1.1 多语言支持机制

#### 1.1.1 语言指定方式

|方式|示例|优先级|
| ----------| ------------------------| --------|
|URL参数|`/api/jobs?lang=en`|最高|
|HTTP头|`Accept-Language: zh-CN`|中等|
|用户偏好|登录用户设置的默认语言|低|
|系统默认|配置的默认语言|最低|

#### 1.1.2 多语言数据返回格式

```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Software Engineer",
    "description": "We are looking for a talented software engineer...",
    // 其他字段
  },
  "i18n": {
    "messages": {
      "common.success": "操作成功",
      "job.apply.success": "申请提交成功"
    }
  }
}
```

### 1.2 认证与授权

#### 1.2.1 JWT认证

- 登录成功后返回JWT token
- 所有需要认证的接口需在请求头中携带 ​`Authorization: Bearer <token>`
- token有效期：24小时

#### 1.2.2 角色权限

|角色|权限范围|
| ------| --------------|
|`candidate`|应聘者功能|
|`company_admin`|企业管理功能|
|`super_admin`|系统管理功能|

## 2. 公共接口

### 2.1 获取支持的语言列表

```http
GET /api/languages
```

#### 响应示例

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "en",
      "name": "English",
      "is_default": true
    },
    {
      "id": 2,
      "code": "zh-CN",
      "name": "简体中文",
      "is_default": false
    }
  ]
}
```

### 2.2 获取国家列表

```http
GET /api/countries
```

#### 响应示例

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "CN",
      "name": "China",
      "currency": "CNY"
    },
    {
      "id": 2,
      "code": "US",
      "name": "United States",
      "currency": "USD"
    }
  ]
}
```

### 2.3 获取地区列表

```http
GET /api/regions?country_id=1
```

#### 响应示例

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "country_id": 1,
      "name": "Beijing"
    },
    {
      "id": 2,
      "country_id": 1,
      "name": "Shanghai"
    }
  ]
}
```

## 3. 用户认证接口

### 3.1 用户注册

```http
POST /api/auth/register
```

#### 请求体

```json
{
  "email": "user@example.com",
  "password": "password123",
  "role": "candidate",
  "language_id": 1
}
```

#### 响应示例

```json
{
  "success": true,
  "data": {
    "id": 1,
    "email": "user@example.com",
    "role": "candidate",
    "language_id": 1
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### 3.2 用户登录

```http
POST /api/auth/login
```

#### 请求体

```json
{
  "email": "user@example.com",
  "password": "password123"
}
```

#### 响应示例

```json
{
  "success": true,
  "data": {
    "id": 1,
    "email": "user@example.com",
    "role": "candidate",
    "language_id": 1
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "i18n": {
    "messages": {
      "auth.login.success": "登录成功"
    }
  }
}
```

### 3.3 忘记密码

```http
POST /api/auth/forgot-password
```

#### 请求体

```json
{
  "email": "user@example.com"
}
```

## 4. 应聘者接口

### 4.1 简历管理

#### 4.1.1 获取简历列表

```http
GET /api/candidates/resumes
```

#### 响应示例

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "file_name": "resume.pdf",
      "file_type": "pdf",
      "size": 1024000,
      "is_default": true,
      "status": "approved"
    }
  ]
}
```

#### 4.1.2 上传简历

```http
POST /api/candidates/resumes/upload
Content-Type: multipart/form-data
```

#### 请求体

- `file`: 简历文件
- `is_default`: 是否设为默认简历

#### 4.1.3 设置默认简历

```http
PUT /api/candidates/resumes/{id}/default
```

### 4.2 职位搜索

```http
GET /api/jobs
```

#### 查询参数

|参数|类型|描述|
| --------------------| ---------| ------------------------------------------|
|keyword|string|搜索关键词|
|job\_type|string|职位类型（full\_time, part\_time）|
|job\_category|string|职位类别（tech, marketing）|
|country\_id|integer|国家ID|
|region\_id|integer|地区ID|
|salary\_min|number|最低工资|
|salary\_max|number|最高工资|
|experience\_min|integer|最低经验（年）|
|page|integer|页码|
|page\_size|integer|每页数量|
|lang|string|语言代码|

#### 响应示例

```json
{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": 1,
        "title": "Software Engineer",
        "company": {
          "id": 1,
          "name": "Tech Company",
          "logo": "https://example.com/logo.png"
        },
        "job_type": "full_time",
        "job_category": "tech",
        "location": "Beijing, China",
        "salary": "15K-25K CNY",
        "experience": "3-5 years"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 100,
      "total_pages": 10
    }
  }
}
```

### 4.3 职位详情

```http
GET /api/jobs/{id}
```

#### 响应示例

```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "Software Engineer",
    "description": "We are looking for a talented software engineer...",
    "requirements": "- Bachelor's degree in Computer Science\n- 3+ years of experience...",
    "responsibilities": "- Develop and maintain web applications\n- Collaborate with cross-functional teams...",
    "benefits": "- Competitive salary\n- Flexible working hours...",
    "company": {
      "id": 1,
      "name": "Tech Company",
      "description": "A leading tech company specializing in...",
      "website": "https://example.com",
      "logo": "https://example.com/logo.png"
    },
    "job_type": "full_time",
    "job_category": "tech",
    "country": "China",
    "region": "Beijing",
    "salary_min": 15000,
    "salary_max": 25000,
    "currency": "CNY",
    "experience_min": 3,
    "experience_max": 5,
    "education_level": "bachelor"
  }
}
```

### 4.4 投递申请

```http
POST /api/jobs/{id}/apply
```

#### 请求体

```json
{
  "resume_id": 1,
  "cover_letter": "I am very interested in this position..."
}
```

### 4.5 我的申请

```http
GET /api/candidates/applications
```

#### 查询参数

- `status`: 申请状态（pending, reviewed, accepted, rejected）
- `page`: 页码
- `page_size`: 每页数量

### 4.6 我的收藏

```http
GET /api/candidates/favorites
```

#### 4.6.1 添加收藏

```http
POST /api/candidates/favorites
```

#### 请求体

```json
{
  "entity_type": "job",
  "entity_id": 1
}
```

#### 4.6.2 取消收藏

```http
DELETE /api/candidates/favorites/{id}
```

## 5. 企业接口

### 5.1 企业信息管理

#### 5.1.1 获取企业信息

```http
GET /api/companies/me
```

#### 5.1.2 更新企业信息

```http
PUT /api/companies/me
```

#### 请求体

```json
{
  "name": "Tech Company",
  "description": "A leading tech company...",
  "website": "https://example.com",
  "country_id": 1,
  "region_id": 1,
  "logo": "https://example.com/logo.png"
}
```

### 5.2 职位管理

#### 5.2.1 发布职位

```http
POST /api/companies/jobs
```

#### 请求体

```json
{
  "title": "Software Engineer",
  "description": "We are looking for a talented software engineer...",
  "requirements": "- Bachelor's degree in Computer Science...",
  "responsibilities": "- Develop and maintain web applications...",
  "benefits": "- Competitive salary...",
  "job_type_id": 1,
  "job_category_id": 1,
  "country_id": 1,
  "region_id": 1,
  "salary_min": 15000,
  "salary_max": 25000,
  "currency": "CNY",
  "experience_min": 3,
  "experience_max": 5,
  "education_level": "bachelor"
}
```

#### 5.2.2 获取企业职位列表

```http
GET /api/companies/jobs
```

#### 查询参数

- `status`: 职位状态（active, inactive）
- `page`: 页码
- `page_size`: 每页数量

#### 5.2.3 更新职位

```http
PUT /api/companies/jobs/{id}
```

#### 5.2.4 下架职位

```http
PUT /api/companies/jobs/{id}/deactivate
```

### 5.3 简历管理

#### 5.3.1 获取收到的简历

```http
GET /api/companies/applications
```

#### 查询参数

- `job_id`: 职位ID
- `status`: 申请状态
- `page`: 页码
- `page_size`: 每页数量

#### 5.3.2 查看简历详情

```http
GET /api/companies/applications/{id}/resume
```

#### 5.3.3 更新申请状态

```http
PUT /api/companies/applications/{id}/status
```

#### 请求体

```json
{
  "status": "reviewed",
  "notes": "Good candidate, schedule an interview"
}
```

### 5.4 面试管理

#### 5.4.1 发起面试

```http
POST /api/companies/interviews
```

#### 请求体

```json
{
  "application_id": 1,
  "interview_date": "2024-01-15T14:00:00Z",
  "interview_type": "online",
  "location": "https://meeting.example.com/123",
  "notes": "Please prepare for technical interview"
}
```

#### 5.4.2 获取面试列表

```http
GET /api/companies/interviews
```

## 6. 多语言内容管理接口

### 6.1 动态内容翻译

#### 6.1.1 获取实体翻译

```http
GET /api/i18n/translations/{entity_type}/{entity_id}
```

#### 6.1.2 添加/更新翻译

```http
POST /api/i18n/translations
```

#### 请求体

```json
{
  "language_id": 2,
  "entity_type": "job",
  "entity_id": 1,
  "field_name": "title",
  "translation": "软件工程师"
}
```

### 6.2 静态内容翻译

#### 6.2.1 获取静态内容翻译

```http
GET /api/i18n/content/{content_key}
```

#### 6.2.2 添加/更新静态内容翻译

```http
POST /api/i18n/content
```

#### 请求体

```json
{
  "language_id": 2,
  "content_key": "home.title",
  "content_value": "欢迎来到招聘网站"
}
```

## 7. 管理员接口

### 7.1 语言管理

#### 7.1.1 添加语言

```http
POST /api/admin/languages
```

#### 请求体

```json
{
  "code": "fr",
  "name": "Français",
  "is_default": false
}
```

#### 7.1.2 设置默认语言

```http
PUT /api/admin/languages/{id}/default
```

### 7.2 国家/地区管理

#### 7.2.1 添加国家

```http
POST /api/admin/countries
```

#### 请求体

```json
{
  "code": "JP",
  "name": "Japan",
  "currency": "JPY"
}
```

#### 7.2.2 添加地区

```http
POST /api/admin/regions
```

#### 请求体

```json
{
  "country_id": 3,
  "name": "Tokyo"
}
```

### 7.3 用户管理

#### 7.3.1 获取用户列表

```http
GET /api/admin/users
```

#### 查询参数

- `role`: 用户角色
- `status`: 用户状态
- `page`: 页码
- `page_size`: 每页数量

#### 7.3.2 更新用户状态

```http
PUT /api/admin/users/{id}/status
```

#### 请求体

```json
{
  "status": "active"
}
```

## 8. WebSocket实时通知接口

### 8.1 连接WebSocket

    ws://example.com/ws?token={jwt_token}

### 8.2 通知类型

|类型|描述|
| -----------------------------------| --------------|
|application\_status\_change|申请状态变更|
|interview\_scheduled|面试安排|
|new\_application|新的职位申请|
|message\_received|收到新消息|

### 8.3 通知数据格式

```json
{
  "type": "application_status_change",
  "data": {
    "application_id": 1,
    "job_title": "Software Engineer",
    "status": "reviewed",
    "notes": "Good candidate"
  },
  "i18n": {
    "message": "您的申请状态已更新为：已查看"
  }
}
```

## 9. 错误码规范

|错误码|描述|HTTP状态码|
| --------| ----------------| ------------|
|20000|操作成功|200|
|40000|请求参数错误|400|
|40100|未授权|401|
|40300|权限不足|403|
|40400|资源不存在|404|
|40900|资源冲突|409|
|50000|服务器内部错误|500|
|50001|数据库错误|500|
|50002|第三方服务错误|500|

## 10. 示例请求响应

### 10.1 职位详情请求（中文）

```http
GET /api/jobs/1?lang=zh-CN
Authorization: Bearer <token>
```

### 10.2 职位详情响应（中文）

```json
{
  "success": true,
  "data": {
    "id": 1,
    "title": "软件工程师",
    "description": "我们正在寻找一位才华横溢的软件工程师...",
    "requirements": "- 计算机科学学士学位...",
    "responsibilities": "- 开发和维护Web应用...",
    "benefits": "- 有竞争力的薪资...",
    "company": {
      "id": 1,
      "name": "科技公司",
      "logo": "https://example.com/logo.png"
    },
    "job_type": "全职",
    "job_category": "技术",
    "location": "中国，北京",
    "salary": "15K-25K CNY",
    "experience": "3-5年"
  },
  "i18n": {
    "messages": {
      "job.detail.view": "查看职位详情",
      "job.apply": "立即申请",
      "job.favorite": "收藏职位"
    }
  }
}
```

## 11. API版本控制

- API版本通过URL前缀控制，如 ​`/api/v1/jobs`
- 支持多版本并存，便于平滑升级
- 新版本API需保持向后兼容

## 12. 安全规范

1. **HTTPS**：所有API请求必须使用HTTPS
2. **输入验证**：所有请求参数必须严格验证
3. **输出过滤**：所有响应数据必须过滤敏感信息
4. **速率限制**：防止API滥用，每个IP或用户设置请求频率限制
5. **SQL注入防护**：使用参数化查询，防止SQL注入
6. **XSS防护**：对输出内容进行HTML转义
7. **CSRF防护**：对非GET请求进行CSRF验证

## 13. 性能优化

1. **缓存策略**：

   - 热门职位、公司信息缓存
   - 翻译内容缓存
   - 静态内容缓存
2. **分页处理**：所有列表接口必须支持分页
3. **异步处理**：

   - 邮件发送异步处理
   - 通知推送异步处理
   - 简历解析异步处理
4. **数据库优化**：

   - 合理设计索引
   - 避免N+1查询
   - 大表分区

## 14. 部署建议

1. **API网关**：使用API网关统一管理API请求，包括认证、限流、监控等
2. **负载均衡**：多实例部署，使用负载均衡分发请求
3. **容器化部署**：使用Docker容器化部署，便于扩展和管理
4. **CI/CD**：实现自动化构建、测试和部署
5. **监控与日志**：

   - 接入APM监控系统
   - 完善的日志记录
   - 实时告警机制

## 15. 文档更新日志

|日期|版本|更新内容|
| ------------| ------| -----------------------|
|2024-01-01|v1.0|初始版本|
|2024-01-15|v1.1|添加WebSocket通知接口|
|2024-02-01|v1.2|完善多语言支持机制|

---

**API文档版本**：v1.2  
**最后更新**：2024-02-01  
**适用系统**：多语言招聘网站