# 岗位搜索 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

```json
{
  "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

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

#### 空数据

```json
{
  "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.*）