獵人頭模組 PRD

產品名稱：獵人頭模組（Headhunter Module）
一句話：讓「誰帶來這份履歷」可追蹤、讓 KOC 能打包推薦、讓夥伴獵頭（奧德士）能獨佔曝光職缺——應徵仍走 WPORT 人才庫管線。
PRD 代號：pm_46（文件夾序號；Coda / Trello 建議用產品名「獵人頭模組」）
子能力：① 推薦歸因（ref / utm_source）② 職缺推薦清單 ③ 夥伴職缺綁定與官網同步
不重複定義：API 金鑰與企業人才庫 UI 沿用 pm_41。
產出 persona：CEO with PM Background（SaaS / HR tech lens）。

1. 文件資訊

2. 專案背景與範圍

2.1 戰略背景：什麼是「獵人頭模組」？

獵人頭模組服務 WPORT 三類獵頭場景，共用同一條應徵與人才庫管線：

核心目標：每一筆應徵都能回答「是誰帶來的？」；夥伴獨佔職缺僅改變 職缺在哪裡曝光，不改變 應徵進哪條人才庫。

2.2 與 pm_41 的邊界（Eric 確認，2026/07/03）

pm_41 是企業端 API 金鑰自助（wpk_live_）與 人才庫畫面 的 SoT；獵人頭模組 不另建 第二套 Key 或獨立機構後台。

綁定奧德士後的產品行為（關鍵）：

換句話說：綁給奧德士的人才，發職缺的公司在 WPORT 人才庫裡一樣看得到；唯一差別是該職缺 不會再出現在 WPORT 公開求職站，改在 奧德士官網 曝光。人才庫體驗對 HR 不變（pm_41 畫面）。

企業 HR 可 主動解約（解除夥伴綁定）→ 職缺恢復 WPORT 公開曝光規則，奧德士 API 與官網同步停止收錄該職缺。

2.3 模組依賴架構

flowchart TB
    subgraph pm41 [pm_41 沿用]
        API[企業 API 金鑰 wpk_live_]
        CRM[企業人才庫 UI]
    end
    subgraph hunter [獵人頭模組 pm_46]
        M1[模組 1：UTM 歸因 P0]
        M2[模組 2：職缺蒐藏清單 P1]
        M3[模組 3：夥伴獨佔職缺綁定 P2]
    end
    M1 --> M2
    M1 --> M3
    M3 --> API
    M3 --> CRM

2.4 範圍界定

包含（v1）

• 職缺可見性三態：PUBLIC / SECRET_URL / DRAFT
• 前端歸因參數擷取與持久化（Cookie + LocalStorage，30 天）；Cookie 橫幅照常顯示，歸因 Cookie 列功能性必要（§11 #2 已決）
• 應徵寫入時自動帶入推薦人 / 夥伴歸因；v1 僅在 applications 加欄位，不建獨立 referrals 表（§11 #3 已決）
• Last Click 歸因、防自推、防重複投遞作弊
• 獨立獵頭職缺蒐藏清單 CRUD 與分享 URL
• 清單內職缺連結自動注入 ref
• 職缺 綁定夥伴獵頭公司（如奧德士）：WPORT 公開站隱藏、夥伴官網 API 同步露出
• 企業 HR 主動解約（解除綁定）
• 夥伴透過 pm_41 公司後台 wpk_live_ Key 拉取已綁定職缺（不另建 wak_live_）

排除（v1 不做）

• 推薦人分潤 / 佣金結算（另案）
• 推薦人儀表板與即時報表（v2）
• 獨立 agency_users 或機構專用登入站（夥伴 = WPORT 公司帳號，Key 走 pm_41）
• 第二套 API Key 前綴（wak_live_）或獨立機構 api_keys 表
• 點擊未投遞的 referral_click_events 漏斗表（v1.1 再議）
• 多點觸控歸因（First Click / Linear）— v1 僅 Last Click
• Webhook 推送應徵事件給夥伴（v2）
• 重複定義 pm_41 人才庫 UI / API 金鑰自助流程

2.5 成功條件（6 個月 KPI）

3. User Stories（使用者故事）

3.1 企業 HR

3.2 一般用戶 / 中間獵頭（Middle Hunter / KOC）

3.3 夥伴獵頭公司（如奧德士 Odexus）

奧德士在 WPORT 上為一般公司帳號（夥伴獵頭公司）；API Key 申請 / 輪替走 pm_41 公司後台，本模組不重複定義 Key UI。

3.4 求職者（附帶）

4. Functional Requirements（功能性需求）

4.1 模組 1：UTM 歸因系統（P0）

FR-1.1 職缺可見性三態

• visibility 與既有 status（上架/下架/已關閉/已刪除）正交：終態職缺（已關閉/已刪除）一律不可投遞，不受 visibility 影響。
• PUBLIC 職缺須滿足 BR-008（必填欄位 + 公司已驗證）方可生效。

FR-1.2 歸因參數擷取（前端）

進入 WPORT 職缺相關頁面時，若 URL 含以下任一參數，前端必須寫入瀏覽器：

儲存策略

• 主要：HttpOnly 不可行（需前端讀取）→ 使用 第一方 Cookie wport_ref（JSON payload，Secure + SameSite=Lax）。
• 備援：localStorage key wport_ref_v1（Cookie 被阻擋時 fallback）。
• 效期：30 天（max-age=2592000）；每次有效點擊帶新參數時覆寫（Last Click）。
• 儲存結構（語意）：

{
  "referrer_type": "user | partner",
  "referrer_id": "string",
  "captured_at": "ISO8601",
  "landing_url": "string",
  "expires_at": "ISO8601"
}

FR-1.3 歸因寫入（後端）

建立 Applications 紀錄時：

1. 讀取請求附帶的歸因 payload（由前端從 Cookie 注入 request header X-Wport-Referral 或 body 欄位 referral）。
2. 後端獨立驗證（不信任前端單方面宣告）：
   • referrer_id 存在且帳號狀態有效（未刪除，BR-012）。
   • referrer_type=user 時，referrer_id ≠ applicant_user_id（禁止自推，BR-039）。
   • referrer_type=partner 時，partner_company_id 存在、為已認證之夥伴獵頭公司且 status=active。
   • 歸因時間未超過 30 天。
3. 驗證通過 → 寫入 Applications.referrer_type、Applications.referrer_id、Applications.referral_captured_at。
4. 驗證失敗 → 應徵仍成功建立，但 referrer_* 為 null（歸因為增值能力，不阻斷核心投遞）。

FR-1.4 歸因原則：Last Click

• 30 天窗口內，最後一次帶有效 ref 或 utm_source 的點擊覆寫先前歸因。
• 若最後一次點擊為無參數的直接進入 → 清除歸因（視為直接投遞）。
• ref 與 utm_source 同時存在於同一 URL 時，優先序：ref > utm_source（個人歸因優先於夥伴）。

FR-1.5 防作弊機制

FR-1.6 與 SEO / Canonical 相容

• 對齊 pm_33：ref / utm_source 為追蹤參數，不影響 Canonical URL（Canonical 指向無查詢參數的乾淨職缺 URL）。
• 搜尋引擎爬蟲不寫入歸因 Cookie（辨識 bot User-Agent 跳過）。

4.2 模組 2：中間獵頭/KOC 職缺蒐藏清單（P1）

FR-2.1 清單生命週期

FR-2.2 職缺加入條件

獵頭用戶僅可加入符合以下任一條件的職缺：

1. visibility = PUBLIC 且 status = 上架 且 bound_partner_company_id IS NULL（未綁定夥伴）
2. visibility = SECRET_URL 且 status = 上架 且存在 job_hunter_assignments 指派給該用戶

綁定夥伴的職缺不在 WPORT 公開站露出，亦不可加入 KOC 蒐藏清單（見 E-24）。

不符合條件的職缺在 UI 顯示為不可選，API 回傳 403 JOB_NOT_ELIGIBLE。

FR-2.3 分享 URL

• 格式：https://wport.co/list/{list_id}?ref={hunter_user_id}
• list_id：不透明 UUID（非自增整數，防枚舉）
• 公開頁：不需登入即可瀏覽清單與職缺摘要
• 清單頁載入時：將 ref 寫入模組 1 歸因 Cookie（與直接職缺連結行為一致）

FR-2.4 動態注入 ref（核心）

當求職者在清單頁點擊任一職缺時，系統必須：

1. 取清單擁有者的 hunter_user_id（來自清單 owner_user_id，非 URL 參數—防篡改）。
2. 生成職缺 URL：/job/{id}/{slug}?ref={owner_user_id}
3. 若 URL 已有 ref，以清單擁有者覆寫（清單場景優先）。
4. 同時更新歸因 Cookie（Last Click）。

設計理由：URL 的 ref 可被使用者手動修改，但清單點擊行為以伺服器端/前端路由守衛強制注入，確保歸因正確。

FR-2.5 清單內容動態更新

• 職缺進入終態（已關閉/已刪除/下架）→ 清單內該項顯示 boundary「此職缺已關閉」，連結停用（對齊 BR-009 / pm_42）。
• 職缺從 SECRET_URL 移除獵頭指派 → 下次清單擁有者儲存時自動剔除該項並通知。

4.3 模組 3：夥伴獨佔職缺綁定與同步（P2）

FR-3.1 夥伴獵頭公司（Partner Company）

• 夥伴（如奧德士）在 WPORT 上為一般 Company 實體，另標記 is_headhunter_partner = true（或等價旗標）。
• 不建獨立 agency_users 登入體系；夥伴員工用 WPORT 統一帳號進入該公司企業後台。
• API Key 核發 / 輪替 / 撤銷 完全沿用 pm_41（公司後台「API 金鑰自助申請」或 AMS 軌道 B）；本模組僅擴充 API 回傳範圍 與 職缺曝光規則。

FR-3.2 職缺綁定夥伴（原「獨佔」）

企業 HR 發布職缺時可選擇「綁定夥伴獵頭」（如奧德士）→ 寫入 bound_partner_company_id（FK → companies.id）。

綁定後行為：

解約（企業主動解除綁定）：

• HR 執行「解除夥伴綁定」→ bound_partner_company_id = NULL。
• 職缺恢復原本 visibility 的 WPORT 曝光規則。
• 奧德士下次 API 同步不再收到該職缺；官網應下架（由奧德士端排程處理）。
• 既有應徵紀錄與人才庫資料保留，不刪除。

非綁定職缺：bound_partner_company_id = NULL；夥伴 API 不可取得其他企業的職缺。

FR-3.3 API Key：沿用 pm_41（不重複定義）

FR-3.4 夥伴拉取已綁定職缺（擴充 pm_41 Enterprise API）

Authorization: Bearer wpk_live_xxxx
GET /v1/jobs?filter=partner_bound

後端流程（Key 須含 jobs:partner_bound_read scope）：

1. 驗證 wpk_live_ → 解析 company_id（奧德士的公司 ID）
2. 確認該 company_id 為 is_headhunter_partner = true
3. 查詢條件強制注入：bound_partner_company_id = {company_id} AND status = 上架
4. 不回傳未綁定職缺、草稿、已關閉職缺
5. 分頁：page, page_size（max 100）

發職缺企業用自家 wpk_live_（職缺 scope）管自己的職缺；奧德士用自家 wpk_live_（partner_bound scope）管別人綁給自己的職缺——同一套 Key 機制，不同 scope 與過濾邏輯。

FR-3.5 夥伴官網導流 URL

API 回傳的 job_url 供奧德士官網投放，格式語意：

https://wport.co/job/{job_id}/{slug}?token={signed_token}&utm_source={partner_company_id}

• signed_token：HMAC-SHA256，payload 含 {job_id, partner_company_id, bound_at}；效期跟隨綁定生命週期（綁定存在即有效，解約即失效）。
• 驗證失敗或已解約 → 職缺頁 403「此連結已失效」。
• 無 token 的 WPORT 公開直達：綁定中職缺 → 404（不在公開站露出）。
• Token 驗證通過 → 可投遞；寫入 utm_source 歸因 Cookie；應徵進發職缺企業的人才庫。

FR-3.6 與 pm_41 的邊界（已決）

5. Non-Functional Requirements（非功能性需求）

5.1 資安（Security）

5.2 效能（Performance）

5.3 API Rate Limiting

回應 Header（沿用 pm_41）：

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1720000000

5.4 可用性與可靠性

5.5 合規與隱私

• Cookie 橫幅：v1 顯示 Cookie 同意橫幅（業界常規）；wport_ref 歸因 Cookie 列為功能性必要 Cookie，於 Cookie / 隱私政策揭露用途（記錄推薦來源以完成應徵歸因）；使用者接受網站 Cookie 後寫入（§11 #2 已決）。
• 推薦人可見範圍：企業 HR 可看應徵的推薦來源（pm_41 人才庫）；推薦人不可看到求職者 PII（v1）。
• 夥伴 API 回傳資料不含求職者個資（僅職缺資訊）。

5.6 可觀測性

• 指標：referral_capture_rate, referral_apply_attribution_rate, partner_bound_api_error_rate
• 告警：夥伴 API 5xx > 1% 持續 5 分鐘 → PagerDuty
• 歸因異常：單日自推嘗試 > 100 次 → 安全日誌

6. Data Models（資料結構模型）

本節為 RD 建表參考。外鍵關聯以 → 標示。索引建議附於各表末。

6.1 ER 關聯總覽

erDiagram
    Companies ||--o{ Jobs : publishes
    Companies ||--o{ Jobs : "bound_partner"
    Users ||--o{ JobLists : owns
    JobLists ||--o{ JobListItems : contains
    Jobs ||--o{ JobListItems : "in list"
    Users ||--o{ JobHunterAssignments : "assigned to"
    Jobs ||--o{ JobHunterAssignments : "assigned job"
    Users ||--o{ Applications : applies
    Jobs ||--o{ Applications : "applied to"
    Users ||--o{ Applications : "referrer (user)"
    Companies ||--o{ Applications : "referrer (partner)"

ApiKey 實體沿用 pm_41，不在此重複定義 ER。

6.2 jobs（升級）

在既有 jobs 表新增欄位：

索引

• idx_jobs_visibility_status (visibility, status) — 搜尋過濾
• idx_jobs_bound_partner (bound_partner_company_id, status) — 夥伴 API 查詢
• idx_jobs_secret_token (secret_url_token) — URL 直達

遷移策略

• 既有上架職缺 → visibility = 'PUBLIC'
• 既有草稿 → visibility = 'DRAFT'
• bound_partner_company_id 預設 NULL（不影響既有職缺）

6.3 companies 擴充（夥伴獵頭公司）

在既有 companies 表新增（或等價設定表）：

索引：idx_companies_partner (is_headhunter_partner) WHERE is_headhunter_partner = true

奧德士 = WPORT 上的一間 Company + is_headhunter_partner=true；API Key 走 pm_41 api_keys 表，不另建 agency_api_keys。

6.4 job_lists（蒐藏清單主表）

索引：idx_job_lists_owner (owner_user_id, status)

約束：每 owner_user_id 的 active 清單 ≤ 20

6.5 job_list_items（清單職缺關聯表）

索引

• uniq_list_job (job_list_id, job_id) — UNIQUE，防重複加入
• idx_list_items_job (job_id)

約束：每 job_list_id 的 items ≤ 50

6.6 job_hunter_assignments（秘密職缺指派）

索引：uniq_job_hunter (job_id, hunter_user_id) — UNIQUE

6.7 applications（歸因欄位擴充）

在既有 applications 表新增：

索引：idx_applications_referrer (referrer_type, referrer_id, created_at)

設計決策（Eric 已決）：v1 不建獨立 referrals / referral_click_events 表；僅在投遞成功時寫入 applications 歸因欄位。應徵者照常進入發職缺企業的人才庫（pm_41 UI）。

7. Edge Cases（異常邊界情況與防呆設計）

7.1 歸因相關

7.2 職缺可見性

7.3 職缺蒐藏清單

7.4 夥伴 API（pm_41 擴充）

7.5 Edge Case Coverage Matrix

8. 商業規則對齊與新增提案

8.1 沿用的既有規則

8.2 建議新增規則（待回寫 business-rules.md）

9. Flowcharts

9.1 歸因 User Flow

flowchart TD
    A[求職者點擊帶 ref/utm 的連結] --> B{URL 參數有效?}
    B -->|否| C[正常瀏覽，不寫歸因]
    B -->|是| D[寫入 Cookie/LocalStorage 30天]
    D --> E[瀏覽職缺/清單]
    E --> F{點擊投遞?}
    F -->|否| G[離開或繼續瀏覽]
    F -->|是| H{已登入且履歷就緒?}
    H -->|否| I[導登入/補資料]
    I --> F
    H -->|是| J[後端驗證歸因]
    J --> K{通過?}
    K -->|是| L[建立 Application + referrer]
    K -->|否| M[建立 Application，referrer=null]
    L --> N[投遞成功]
    M --> N

9.2 清單 → 歸因 System Flow

sequenceDiagram
    participant Seeker as 求職者
    participant ListPage as 清單頁
    participant Cookie as 歸因 Cookie
    participant JobPage as 職缺頁
    participant API as 後端 API

    Seeker->>ListPage: GET /list/{id}?ref={hunter}
    ListPage->>Cookie: 寫入 ref=hunter（Last Click）
    Seeker->>ListPage: 點擊職缺 A
    ListPage->>JobPage: 導向 /job/A?ref={owner_id}（強制注入）
    JobPage->>Cookie: 覆寫 ref=owner_id
    Seeker->>API: POST 應徵 + referral payload
    API->>API: 驗證 ref≠self、未過期、推薦人有效
    API-->>Seeker: 201 應徵成功

9.3 夥伴職缺同步 System Flow

sequenceDiagram
    participant Odexus as 奧德士官網/ATS
    participant API as WPORT API（pm_41）
    participant DB as 資料庫
    participant HR as 發職缺企業人才庫

    Odexus->>API: GET /v1/jobs?filter=partner_bound（wpk_live_）
    API->>API: 驗證 scope + is_headhunter_partner
    API->>DB: SELECT jobs WHERE bound_partner_company_id=奧德士 AND status=上架
    DB-->>API: 職缺列表（含導流 URL）
    API-->>Odexus: 200 JSON
    Note over Odexus: 職缺露出於奧德士官網（非 WPORT 公開站）
    Odexus->>API: 求職者經導流 URL 投遞
    API->>HR: 應徵寫入 applications + 人才庫（pm_41 UI）

10. 版本凍結（v1 / v2）

11. PRD 問題清單

12. 下一步

1. 回寫 BR-039 ~ BR-043 至 business-rules.md
2. 模組 1（P0）後端 + 前端 Cookie 邏輯先行開發
3. 與 pm_41 RD 對齊：新增 scope jobs:partner_bound_read 與 GET /v1/jobs?filter=partner_bound
4. 模組 2 清單頁 Storybook mockup（gen-storybook-mockup-gen）
5. 與奧德士 BD 對齊官網同步與解約流程

文件結束