qingsongping-AIDevelop/docs/company-public-api.md

企业公开主页 API

接口列表

1. GET /api/v1/companies/{companyId}

查询企业公开详情。匿名可访问。

仅返回 6 个公开字段： id, name, logoUrl, description, industry, verified

不返回： ownerUserId, website, address, createdAt, updatedAt, 审核信息

响应 200

{
  "code": 200,
  "message": "ok",
  "data": {
    "id": 1,
    "name": "XX科技有限公司",
    "logoUrl": "https://cdn.example.com/logo.png",
    "description": "专注于企业级软件开发...",
    "industry": "IT",
    "verified": true
  }
}

错误响应

场景	HTTP	code	message
企业不存在	404	5001	company not found

---

2. GET /api/v1/companies/{companyId}/jobs

查询企业公开岗位列表。匿名可访问。

仅返回该企业 status=PUBLISHED 的岗位。

请求参数

参数	类型	必填	默认值	校验
page	int	否	0	>= 0
size	int	否	20	1–50
sort	String	否	latest	latest / salary / relevance

排序规则

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

响应 200

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [
      {
        "id": 1,
        "title": "Java开发工程师",
        "description": "...",
        "requirements": "...",
        "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": 5,
    "page": 0,
    "size": 20,
    "totalPages": 1
  }
}

空结果（企业存在但无 PUBLISHED 岗位）

{
  "code": 200,
  "message": "ok",
  "data": {
    "items": [],
    "total": 0,
    "page": 0,
    "size": 20,
    "totalPages": 0
  }
}

错误响应

场景	HTTP	code	message
企业不存在	404	5001	company not found
page < 0	400	1001	bad request
size < 1 或 > 50	400	1001	bad request
sort 非法	400	1001	bad request

---

兼容性说明

端点	行为
GET /companies/me	完全不变（需登录）
POST /companies/me	完全不变（需登录）
PUT /companies/me	完全不变（需登录）
GET /companies/{companyId}	新增，匿名可访问
GET /companies/{companyId}/jobs	新增，匿名可访问
GET /jobs	完全不变
GET /jobs/search	完全不变
GET /jobs/public/{jobId}	完全不变