check-jobs 爬虫查重与智能顶贴接口文档

用于爬虫在抓取列表页后、进入详情页深度解析与 AI 翻译前，进行前置查重与自动顶贴（Auto-Bump）。

核心价值：

1. 节省 85%+ AI 算力与网络带宽：已存在的职位无需进入详情页爬取，更无需调用大模型翻译 14 国语言。
2. 自动置顶保鲜：原站雇主刷新/顶贴（Bump/끌어올리기）后，开启 auto_bump: true 会自动将该职位发布时间更新为最新，在 APP 首页列表排位跃升至最前列，数据库 0 增加新行。
3. 毫秒级性能：底层命中物理条件索引 uq_job_posts_active_original_url_md5，单次查询或批量比对 $<10\text{ms}$。

---

1. 接口基本信息

• 请求方法：POST（推荐批量）/ GET（快捷单条）
• 请求地址：https://<PROJECT_REF>.supabase.co/functions/v1/check-jobs
• 鉴权方式（支持以下 3 种任选其一）：
  1. Header: x-api-key: <INGEST_JOBS_SECRET>
  2. Header: Authorization: Bearer <INGEST_JOBS_SECRET>
  3. Header: x-signature + x-timestamp（HMAC-SHA256 签名，与 ingest-jobs 完全兼容）

---

2. 请求参数说明

2.1 请求头 (Headers)

2.2 请求体 (Body - POST)

支持以下格式：

格式 A：基于 URL 列表批量查重（最推荐）

{
  "urls": [
    "https://114114korea.com/job_view.php?idx=897928",
    "https://114114korea.com/job_view.php?idx=99999999"
  ],
  "auto_bump": true,
  "cooldown_hours": 6,
  "force_bump": false
}

格式 B：基于外部编号列表查重

{
  "external_refs": [
    "crawler-114-구인정보-897928-51",
    "crawler-114-구인정보-not-exist"
  ],
  "auto_bump": true
}

格式 C：复合对象数组查重

{
  "items": [
    { "url": "https://114114korea.com/job_view.php?idx=897928" },
    { "url": "https://114114korea.com/job_view.php?idx=99999999" }
  ],
  "auto_bump": true
}

2.3 控制参数说明

---

3. 响应格式说明

3.1 批量查询响应示例 (HTTP 200)

{
  "ok": true,
  "summary": {
    "total": 2,
    "duplicate_count": 1,
    "new_count": 1,
    "bumped_count": 1
  },
  "results": [
    {
      "url": "https://114114korea.com/job_view.php?idx=897928",
      "is_duplicate": true,
      "bumped": true,
      "matched_by": "url",
      "existing_job": {
        "id": 78865,
        "status": "active",
        "published_at": "2026-10-22T15:42:32.343Z",
        "updated_at": "2026-10-22T15:42:32.343Z"
      }
    },
    {
      "url": "https://114114korea.com/job_view.php?idx=99999999",
      "is_duplicate": false
    }
  ]
}

若处于防抖冷却期内（未触发重新写库），返回示例：

{
  "url": "https://114114korea.com/job_view.php?idx=897928",
  "is_duplicate": true,
  "bumped": false,
  "bump_reason": "within_cooldown",
  "matched_by": "url",
  "existing_job": { ... }
}

3.2 单条查询快捷响应 (HTTP 200)

当使用 GET 请求或 POST 单个对象时，返回扁平对象，方便直接使用 if (res.is_duplicate)：

{
  "ok": true,
  "is_duplicate": true,
  "bumped": true,
  "matched_by": "url",
  "existing_job": {
    "id": 78865,
    "status": "active",
    "published_at": "2026-10-22T15:42:45.972Z",
    "updated_at": "2026-10-22T15:42:45.972Z"
  },
  "query": {
    "url": "https://114114korea.com/job_view.php?idx=897928"
  }
}

---

4. 推荐业务流：3 级漏斗型智能同步

爬虫系统集成推荐采用“列表页查重分流”设计：

flowchart TD
    A["爬虫抓取列表页 (获得 20~50 个 URL)"] --> B["调用 /check-jobs (带 auto_bump=true)"]
    B --> C{"is_duplicate 判断"}
    C -- "true 且 bumped=true" --> D["[已自动置顶] 排名已刷新至 APP 首页，跳过抓取"]
    C -- "true 且 bumped=false" --> E["[冷却期内] 无需操作，直接跳过"]
    C -- "false" --> F["[全新职位] 进入详情页抓取 + 调用 AI 翻译 + 调 /ingest-jobs 入库"]

---

5. 代码调用示例

5.1 Python 示例

import requests

API_URL = "https://ocfohbkrcdgtrnljrhfj.supabase.co/functions/v1/check-jobs"
HEADERS = {
    "content-type": "application/json",
    "x-api-key": "SDF45345fsdfdsfsf34234"
}

def sync_job_list(page_urls):
    payload = {
        "urls": page_urls,
        "auto_bump": True,
        "cooldown_hours": 6
    }
    res = requests.post(API_URL, headers=HEADERS, json=payload).json()

    for item in res.get("results", []):
        url = item["url"]
        if item["is_duplicate"]:
            if item.get("bumped"):
                print(f"[置顶成功] {url} 线上排名已刷新")
            else:
                print(f"[跳过] {url} 6小时内已刷新过")
            continue

        # 仅对新职位发起抓取与入库
        print(f"[新职位] {url} 开始采集详情与入库...")
        detail = crawl_detail(url)
        ingest_to_db(detail)

5.2 cURL 示例

curl -X POST https://ocfohbkrcdgtrnljrhfj.supabase.co/functions/v1/check-jobs \
  -H "content-type: application/json" \
  -H "x-api-key: SDF45345fsdfdsfsf34234" \
  -d '{
    "urls": ["https://114114korea.com/job_view.php?idx=897928"],
    "auto_bump": true
  }'