# 职来后端 API v0.2（第 1 天草案）

> 目标：形成“企业发布岗位—学生浏览—学生投递—企业处理”的最小业务闭环。
> 本文件是开发前契约，接口实现完成后再同步到 Apifox。

基础路径：`/api/v1`

## 角色约定

| 角色 | 权限 |
| --- | --- |
| STUDENT | 查看已发布岗位、维护自己的资料、投递岗位、查看自己的投递 |
| COMPANY | 维护企业资料、创建和管理自己公司的岗位、处理自己岗位的投递 |
| ADMIN | 预留后台管理权限，本轮不实现管理端页面 |

除岗位公开列表和详情外，本轮接口均要求 `Authorization: Bearer <accessToken>`。

## 个人资料

### `GET /profile/me`

返回当前学生的资料；没有资料时返回空对象，不自动创建业务字段。

### `PUT /profile/me`

请求示例：

```json
{
  "realName": "张三",
  "bio": "Java 后端开发",
  "location": "杭州",
  "education": "本科",
  "school": "示例大学",
  "graduationYear": 2027,
  "resumeUrl": "https://cdn.example.com/resume/1.pdf",
  "skills": ["Java", "Spring Boot", "MySQL"]
}
```

### `GET /companies/me`

返回当前企业账号绑定的企业资料。

### `PUT /companies/me`

请求字段：`name`、`logoUrl`、`description`、`industry`、`website`、`address`。

## 岗位

### `POST /jobs`

仅 `COMPANY` 可调用。

```json
{
  "title": "Java 后端工程师",
  "description": "负责服务端业务开发",
  "requirements": "熟悉 Spring Boot",
  "city": "杭州",
  "employmentType": "FULL_TIME",
  "salaryMin": 8000,
  "salaryMax": 15000
}
```

新岗位默认状态为 `DRAFT`。

### `PUT /jobs/{jobId}`

仅岗位所属企业可修改草稿或已发布岗位。

### `PATCH /jobs/{jobId}/status`

请求示例：

```json
{ "status": "PUBLISHED" }
```

允许状态：`DRAFT`、`PUBLISHED`、`CLOSED`。

### `GET /jobs/{jobId}`

返回岗位详情。已关闭岗位仍允许查看详情，但不可新投递。

### `GET /jobs`

查询参数：

| 参数 | 说明 |
| --- | --- |
| `keyword` | 标题、描述关键词 |
| `city` | 工作城市 |
| `employmentType` | 用工类型 |
| `salaryMin` | 最低薪资 |
| `salaryMax` | 最高薪资 |
| `page` | 从 0 开始，默认 0 |
| `size` | 默认 20，最大 50 |

默认只返回 `PUBLISHED` 岗位，并按发布时间倒序。

## 投递

### `POST /jobs/{jobId}/applications`

仅 `STUDENT` 可调用。

```json
{ "coverLetter": "希望加入贵公司。" }
```

同一学生对同一岗位只能投递一次。

### `GET /applications/me`

学生查看自己的投递记录，支持 `status`、`page`、`size`。

### `GET /company/applications`

企业查看自己公司岗位收到的投递，支持 `jobId`、`status`、`page`、`size`。

### `PATCH /applications/{applicationId}/status`

仅岗位所属企业可调用。

```json
{ "status": "INTERVIEW" }
```

允许状态：`SUBMITTED`、`VIEWED`、`INTERVIEW`、`REJECTED`、`HIRED`。

## 统一错误验收

- 未登录：`401`
- 无角色权限：`403`
- 参数错误：`400`
- 重复投递：`409`
- 岗位不存在：`404`
- 非法状态流转：`409`

所有响应继续使用现有 `ApiResponse` 和 `PageResponse` 格式。