qingsongping-AIDevelop/docs/api-v0.2-draft.md

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

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

基础路径：/api/v1

角色约定

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

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

个人资料

GET /profile/me

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

PUT /profile/me

请求示例：

{
  "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 可调用。

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

新岗位默认状态为 DRAFT。

PUT /jobs/{jobId}

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

PATCH /jobs/{jobId}/status

请求示例：

{ "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 可调用。

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

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

GET /applications/me

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

GET /company/applications

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

PATCH /applications/{applicationId}/status

仅岗位所属企业可调用。

{ "status": "INTERVIEW" }

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

统一错误验收

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

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