zhangshun/docs/job-search-api.md

岗位搜索 API

接口列表

1. GET /api/v1/jobs/search

岗位高级搜索。仅返回 PUBLISHED 岗位，CLOSED 和 DRAFT 不出现在结果中。

公开访问，无需认证。

请求参数

参数	类型	必填	默认值	说明
keyword	String	否	-	搜索标题/描述/要求关键词
city	String	否	-	城市精确匹配
employmentType	String	否	-	用工类型精确匹配
salaryMin	Integer	否	-	最低薪资筛选（岗位 salaryMax >= salaryMin）
salaryMax	Integer	否	-	最高薪资筛选（岗位 salaryMin <= salaryMax）
companyId	Long	否	-	按公司筛选
sort	String	否	latest	latest / salary / relevance
page	int	否	0	页码，>= 0
size	int	否	20	每页条数，1-50

排序规则

sort 值	排序
latest（默认）	createdAt DESC, id DESC
salary	salaryMax DESC, id DESC
relevance	createdAt DESC, id DESC（本期按 latest 兜底）

薪资筛选规则

• salaryMin：仅返回 job.salaryMax >= salaryMin 的岗位
• salaryMax：仅返回 job.salaryMin <= salaryMax 的岗位
• salaryMin > salaryMax 返回 400 (code=1001)
• 薪资字段为 NULL 的岗位不参与薪资范围筛选

错误码

场景	HTTP	code
salaryMin > salaryMax	400	1001
sort 非法值	400	1001
page < 0	400	1001
size < 1 或 size > 50	400	1001

响应 200

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "Java开发工程师",
        "description": "负责后端服务开发...",
        "requirements": "3年以上Java经验...",
        "city": "北京",
        "employmentType": "FULL_TIME",
        "salaryMin": 15000,
        "salaryMax": 25000,
        "status": "PUBLISHED",
        "publishedAt": "2026-08-01T10:00:00",
        "createdAt": "2026-08-01T09:00:00",
        "company": {
          "id": 1,
          "name": "XX科技有限公司",
          "logoUrl": "https://cdn.example.com/logo.png",
          "verified": true
        }
      }
    ],
    "total": 100,
    "page": 0,
    "size": 20,
    "totalPages": 5
  }
}

---

2. GET /api/v1/jobs/filters

岗位筛选选项。数据仅来自 PUBLISHED 岗位。

公开访问，无需认证。

响应 200

{
  "code": 200,
  "message": "ok",
  "data": {
    "cities": ["北京", "上海", "深圳"],
    "employmentTypes": ["FULL_TIME", "INTERN", "PART_TIME"],
    "salaryRange": {
      "min": 5000,
      "max": 50000
    }
  }
}

空数据

{
  "cities": [],
  "employmentTypes": [],
  "salaryRange": {
    "min": null,
    "max": null
  }
}

排序规则

• cities：按城市名自然排序（ASC），去重
• employmentTypes：按枚举值自然排序（ASC），去重
• salaryRange：min 取 MIN(salaryMin)，max 取 MAX(salaryMax)，排除 NULL

---

3. 兼容性说明

端点	行为
GET /jobs	完全不变。路径、参数、返回结构、状态码、权限语义均保持现有实现。
GET /jobs/public/{jobId}	完全不变。PUBLISHED 和 CLOSED 均可查看详情。
GET /jobs/search	新增。仅返回 PUBLISHED。
GET /jobs/filters	新增。仅基于 PUBLISHED。

---

公开 DTO 字段

搜索结果仅返回以下公开字段，不泄露：

• ownerUserId（企业关联用户）
• 企业联系方式（website、address）
• 企业内部时间戳（updatedAt）
• 审核信息（company_verifications.*）