企業人才 CRM（收藏人才＋標籤＋訪客時間軸去重）Mockup PRD（給後端 API 規格產生器使用）

整合三項：企業收藏人才、貼標籤、人才卡片重複出現優化（訪客去重 + 時間軸 + 熱度）。 產出 persona：CEO with PM Background（SaaS / HR tech lens）。 架構流派：採 國際 SaaS / ATS 流派（LinkedIn Recruiter、HubSpot CRM）——後台合併去重、時間覆蓋、詳情時間軸、防抖、動態熱度。不採 104/1111 的功能拆裂（誰來看我 vs 應徵名單分離）。

1. 文件資訊

• 文件類型：Mockup 需求規格書（前後端共用視圖）
• 適用對象：前端、後端、產品、QA
• 最後更新：2026/06/23
• 版本：1.0.0
• 對應 Storybook：storybook/src/stories/mockups/recruitment/TalentCrm.stories.ts（已產出，歸於 Mockups/公司/人才 CRM 來訪）
• Storybook 連結：https://storybook.wport.me/?path=/docs/mockups-recruitment-talentcrm—docs
• 建立日期：2026/06/23
• Coda backlog：需新增列（建議名稱：企業人才 CRM（收藏＋標籤＋訪客時間軸））

2. 開發進度與設計來源

開發進度

• 前端 PR #：[TBD]　後端 PR #：[TBD]

設計來源

• Figma：[待補上]
• 既有畫面：企業後台「查詢人才 / 誰來看我 / 應徵名單」框架（recruitment app）；本案將其升級為單一「人才關係」視圖

3. 模擬頁面摘要

3.1 功能概述

• 功能名稱：企業人才 CRM
• 主要使用者角色：Employer（Owner / Admin / Manager；依 BR-016）
• 核心目標：
  • 把 HR 後台從「靜態名單」收斂為 ATS 主流模型：人才 → 加入專案（Project）→ pipeline 階段，外加去重時間軸、熱度訊號、彈性標籤、共用協作動態（防撞車）。
  • 服務 B 端付費轉化 / 留存：pipeline 協作 + 熱度洞察是與傳統人力銀行的差異化與年費黏著；本期標籤、專案、收藏皆免費、不分級（付費鉤子改以熱度洞察 / 進階分析為未來槓桿）。
  • 與傳統人力銀行（104/1111 功能拆裂、數據斷裂、無 pipeline/團隊協作）形成差異化。

3.2 範圍界定（ATS 主流模型：人才 → 專案 → 階段）

• 包含範圍：
  • 人才列表（List View）：一人一列（後台合併去重 BR-030），狀態顯示「最後結果」（應徵 > 收藏 > 查看），足跡 +N、熱度標、所屬專案/當前階段 chips。
  • 人才專案 Project（BR-034，主軸）：「加入專案（save-to-project）」為組織人才主要動作，取代收藏；專案綁職缺、團隊成員共用，可設私人專案。
  • Pipeline 階段（BR-038，ATS 核心）：人才於專案內具階段（待聯繫→已聯繫→篩選中→面試→錄取→婉拒），可切換；列表/詳情可依階段篩選。
  • 標籤（BR-033，彈性 label）：官方共用＋個人標籤（技能/來源/特質）；不兼任階段。
  • 共用人才動態 Timeline（BR-035，防撞車）：互動軸（求職者 view/save/apply）＋ HR 協作軸（加入專案/切換階段/貼標/邀約，署名+時間）。
  • 去重/防抖（BR-030/031）＋熱度（BR-032，MVP-lite）：5 分鐘 debounce、48h≥3 次標高熱度。
  • 收藏（我的最愛，BR-033）：降級為個人 shortlist 捷徑，不在主流程。
• 排除範圍：
  • 公司自訂 pipeline 階段（v2；v1 用固定階段集）。
  • 專案看板（Kanban）拖拉檢視（v2；v1 用列表 + 階段切換/篩選）。
  • 自動評分 / AI 排名（v2；可串既有 AI 資產）。
  • 跨公司共享人才庫（另案：人才庫履歷分享）。
  • 站內信 / 邀約流程本體（另案：邀約狀態追蹤）—— 本案只在詳情提供「發出邀約」入口 + 於協作軸記錄。

3.3 成功條件

• 同一人在列表永不重複出現；多次互動以 +N 與詳情 Timeline 呈現。
• HR 能一眼判斷「此人關注我們多久 / 是否高意願」（時間軸 + 熱度）。
• 標籤 / 收藏（我的最愛）為對應範圍可存取（官方共用 / 個人私有，BR-033）；被求職者封鎖者不出現（pm_44 BR-027）。
• 任一 HR 進同一人才頁，皆能於共用協作軸看到他人操作（防撞車，BR-035）。
• 標籤與收藏（我的最愛）本期免費、不分級；熱度 / 協作體驗為差異化價值。

4. 商業規則對齊

4.1 本功能使用到的業務規則

4.2 補充說明（已裁決，回寫 business-rules.md；ATS 收斂版 v1.6.0）

Eric 2026/06/24 兩問確認（皆沿用既有裁決，不改方向）：

1. 「來訪以人為主，還是以職缺為主？」→ 以人（求職者）為主。聚合鍵＝求職者（BR-030）：同一人遊覽多個職缺收斂成一張人才卡（一列），跨職缺的 view/save/apply 於詳情 Timeline 合併呈現；不以職缺為主、不每職缺各一張卡（與 104/1111「誰來看我 vs 應徵名單」拆裂模型明確不同）。
2. 「團隊專案誰可 CRUD？」→ Owner / Admin / Manager（BR-036）。Member 唯讀或不可見；公司層級（團隊）專案與官方標籤之維護建議再收斂至 Admin 以上。私人專案僅其擁有者可見/管理。

• BR-030（人才互動聚合與去重）：
  • 同一求職者對同一公司的所有互動（查看職缺 / 收藏職缺 / 應徵）在列表聚合為一列（聚合鍵＝求職者）。
  • 列表狀態 = 互動優先序最高者：applied > saved > viewed。
  • 列表時間 = 最新一次有效互動時間。
  • 足跡計數 +N = 有效互動總數（去重後）。
• BR-031（防抖 / 有效互動定義）：同一求職者對同一職缺，5 分鐘內的重覆查看僅計 1 次有效互動（debounce）；應徵與收藏為事件型，各自計 1 次（不 debounce）。
• BR-032（熱度）：同一求職者對同一職缺，48 小時內有效查看 ≥ 3 次 → 標記 high_engagement；列表可置頂 / 篩選。
• BR-033（標籤・半共用制）：兩類標籤並存——
  • 官方標準標籤：全公司共用（如 #初審通過、#技術黑客），由具管理權限者維護，所有成員遵循。
  • 個人標籤：HR 私有（含「我的最愛」），僅本人可見 / 過濾。
  • 「收藏人才」即以「我的最愛」個人標籤實作，免費、不分級（原收藏付費分級提案取消）。
  • 上限：官方標籤 30 / 公司、個人標籤 30 / HR；名稱 ≤ 12 字 + 顏色；單一人才可多標籤。
• BR-034（人才專案 Project，ATS 主軸）：「加入專案」為組織人才主要動作（取代收藏）；專案綁職缺、團隊成員共用（如「台北前端工程師」）；另提供私人專案（Private Project），僅該 HR 可見（獵頭隱私需求）。一人才可同時在多專案。
• BR-035（共用人才動態 Timeline・防撞車）：人才 Profile 的動態對全公司 HR 共用，顯示操作者與時間，避免重複作業，例：「HR 小美 已於 2026/06/23 將此人才加入「桃園專案」，階段：篩選中」。含兩條軸：① 求職者對本公司之互動軸（view/save/apply，對齊 BR-030）；② HR 協作軸（加入專案 / 切換階段 / 貼標 / 邀約，署名 + 時間）。私人專案（BR-034）之動作不對其他 HR 顯示。
• BR-036（角色權限）：Owner/Admin/Manager 可檢視人才 CRM、加入專案、切換階段、貼標；專案的 CRUD（建立 / 改名 / 改綁定職缺 / 改成員 / 刪除）＝ Owner/Admin/Manager；Member 唯讀或不可見（對齊 BR-016 / BR-017）。官方標籤與公司層級（團隊）專案之維護建議再限 Admin 以上；私人專案之 CRUD 僅其擁有者本人。
• BR-037（資料保留）：人才互動明細保留 1 年（365 天）（聚合計數可更久，明細時間軸滾動保留）；與 BR-019 一併視為資料保留口徑。

5. 資料實體與欄位

5.1 實體列表

5.2 TypeScript 介面（語意用途；命名待與 Storybook 對齊）

interface TalentRow {
  enc_id: string;                  // 人才（求職者）對本公司之聚合列 ID
  candidate: {
    enc_id: string;
    display_name: string;          // 依平台隱私規則顯示（可能遮罩）
    headline?: string;
    avatar_url?: string;
  };
  latest_status: 'applied' | 'saved' | 'viewed';   // 最後結果（BR-030 優先序）
  latest_interaction_at: string;   // 最新一次有效互動時間（BR-030）
  interaction_count: number;       // 足跡 +N（去重後，BR-030/031）
  is_high_engagement: boolean;     // BR-032
  memberships: ProjectMembership[];// 所屬專案與當前階段（BR-034/038）
  tags: TalentTag[];               // 已套用彈性 label
  is_favorited?: boolean;          // 個人 shortlist（我的最愛，BR-033，降級）
}

interface TalentInteraction {
  enc_id: string;
  type: 'viewed' | 'saved' | 'applied';
  job: { enc_id: string; title: string };
  occurred_at: string;             // ISO8601
  view_seq?: number;               // 第 N 次查看（type=viewed 時）
}

// 人才專案（ATS 主軸，BR-034）
interface Project {
  enc_id: string;
  name: string;                        // 例：台北前端工程師
  visibility: 'team' | 'private';      // 團隊成員共用 / 私人專案
  job_enc_id?: string;                 // 綁定的職缺（可選）
  member_hr_enc_ids?: string[];        // visibility=team 的專案成員
  owner_hr_enc_id?: string;            // visibility=private 的擁有者
}

// 人才在某專案內的歸屬與 pipeline 階段（BR-034/038）
interface ProjectMembership {
  project_enc_id: string;
  project_name: string;
  stage_code: PipelineStage;
  added_by_hr: { enc_id: string; name: string };
  added_at: string;
}

// v1 固定階段集（BR-038）；自訂階段為 v2
type PipelineStage =
  | 'to_contact'   // 待聯繫
  | 'contacted'    // 已聯繫
  | 'screening'    // 篩選中
  | 'interview'    // 面試
  | 'offer'        // 錄取
  | 'rejected';    // 婉拒

interface TalentTag {
  enc_id: string;
  name: string;                    // ≤ 12 字
  color: string;                   // 顏色代碼/列舉（語意，不規定 hex 來源）
  scope: 'official' | 'personal';  // 官方共用 / 個人私有（BR-033）
  is_favorite?: boolean;           // personal 之「我的最愛」shortlist（降級，免費）
  owner_hr_enc_id?: string;        // scope=personal 時的擁有者
}

// HR 協作動態（防撞車，BR-035）— 與 TalentInteraction（求職者互動軸）分屬兩條軸
interface TalentActivity {
  enc_id: string;
  actor_hr: { enc_id: string; name: string };   // 操作者（署名）
  action: 'added_to_project' | 'stage_changed' | 'tagged' | 'invited' | 'note' | 'favorited';
  target_label?: string;            // 例：專案名「桃園專案」/ 階段「篩選中」/ 標籤名
  occurred_at: string;
  is_private?: boolean;             // 私人專案動作不對其他 HR 顯示
}

6. 畫面區塊與資料需求

6.1 區塊列表

6.2 各區塊資料需求

SEC-1 人才列表

• 顯示實體：TalentRow[]；分頁、排序（預設 latest_interaction_at desc；高熱度可置頂）
• 顯示規則：
  • 一人一列（BR-030 去重）。
  • 足跡 icon + +N（interaction_count）。
  • is_high_engagement → 顯示熱度標（如閃電/大腦 icon）+ 可選置頂。
  • 已排除：被該求職者封鎖本公司者（pm_44 BR-027 #3）。

SEC-2 篩選列

• 元件：關鍵字、互動狀態（applied/saved/viewed）、專案、pipeline 階段、標籤多選、熱度開關、僅看我的最愛
• 是否即時打 API：關鍵字 debounce 300ms；其餘即時

SEC-3 人才詳情（雙軸 Timeline，BR-035）

• 內容：履歷主體（沿用既有履歷檢視）+ 右側 Timeline，含兩條軸：
  • 互動軸（TalentInteraction[]，求職者行為，新到舊）：6/04 14:00 投遞了履歷 / 6/03 11:00 第 3 次查看職缺 / 5/28 09:00 收藏職缺 / 5/20 16:00 首次查看職缺
  • HR 協作軸（TalentActivity[]，防撞車）：6/05 09:30 HR 小美 將此人才加入「桃園專案」 / 6/05 11:00 HR 小美 將階段改為 篩選中 / 6/05 09:31 HR 小美 貼上 #技術黑客（私人專案動作不顯示給他人）
• 操作：加入專案、切換 pipeline 階段、套用標籤（官方/個人）、我的最愛 toggle、發出邀約（連結至既有邀約流程）；每個操作寫入協作軸並署名

SEC-4 專案 / 階段 / 標籤操作

• 加入專案（BR-034，主操作）：選既有專案或新建（團隊/私人）；加入後出現於該專案 pipeline
• 切換階段（BR-038）：固定階段集下拉/拖拉（待聯繫→…→錄取/婉拒）
• 標籤（BR-033）：官方標籤下拉選既有；個人標籤自建（≤12 + 顏色）；批次貼標為 nice
• 我的最愛（BR-033，降級）：toggle 個人 shortlist，免費

7. 使用者動作與後端需求

8. API Hints

8.1 Read

• HINT-GET-1：人才列表（聚合去重、latest_status、interaction_count、is_high_engagement、排除封鎖）→ SEC-1
• HINT-GET-2：單人互動時間軸（TalentInteraction[]，含 view_seq）→ SEC-3
• HINT-GET-3：公司標籤清單 → SEC-2/SEC-5

8.2 Write

• HINT-MUTATION-1：收藏 / 取消人才（檢核上限 + 角色）
• HINT-MUTATION-2：建立 / 編輯 / 刪除標籤（上限 30）
• HINT-MUTATION-3：套用 / 移除標籤（多對多）

8.3 互動聚合（背景 / 寫入管線）

• HINT-PIPE-1：求職者 view/save/apply 事件寫入 → 後端依 BR-031 debounce（同人同職缺 5 分鐘內查看計 1）→ 更新聚合列（latest_status/time、interaction_count）→ 依 BR-032 計算 high_engagement。
• HINT-PIPE-2：聚合列查詢時 join 求職者封鎖名單，排除已封鎖本公司者（BR-027 #3）。

9. 導航 / Storybook Map

• Storybook 標題：Mockups/企業/人才 CRM
• Stories 路徑：storybook/src/stories/mockups/recruitment/TalentCrm.stories.ts
• 情境控制（建議 args）：scenario（empty / mixed / has-high-engagement / detail-timeline / tag-manage / favorite-limit / member-readonly）、roleCode（OWNER/ADMIN/MANAGER/MEMBER）
• 共用元件 story：TalentRow、InteractionTimeline、TagChip isolation
• CSS profile：recruitment

10. Flowcharts

10.1 User Flow

flowchart TD
    A[企業後台 -> 人才 CRM] --> B{角色可見? BR-036}
    B -- 否(Member) --> B1[唯讀或不可見]
    B -- 是 --> C[人才列表: 一人一列 + +N + 熱度]
    C --> D[篩選: 狀態/標籤/熱度/收藏]
    C --> E[收藏 / 套用標籤]
    C --> F[開啟詳情]
    F --> G[履歷 + 右側 Timeline]
    G --> H[收藏 / 貼標 / 發出邀約]
    E --> I{收藏達免費上限50?}
    I -- 是 --> J[達官方/個人標籤 30 上限提示 BR-033]
    K[標籤管理] --> L{達30上限?}
    L -- 是 --> M[禁用新增 BR-033]

10.2 System Flow（互動聚合與去重）

sequenceDiagram
    participant Seeker as 求職者端
    participant BE as Backend
    participant HR as 企業 HR(前端)
    Seeker->>BE: view/save/apply 事件(job)
    BE->>BE: debounce 同人同職缺 5min 查看計1 (BR-031)
    BE->>BE: 更新聚合列 latest_status/time + interaction_count (BR-030)
    BE->>BE: 48h 查看>=3 -> high_engagement (BR-032)
    HR->>BE: GET 人才列表(篩選)
    BE->>BE: join 封鎖名單排除 (BR-027)
    BE-->>HR: TalentRow[] (去重後)
    HR->>BE: GET 詳情 Timeline
    BE-->>HR: TalentInteraction[] (含第N次查看)

10.4 Edge Case Coverage

11. Mock Data Schema

• 資料來源：僅 mock。
• CRUD 行為：收藏 / 貼標 / 建標籤僅元件狀態，重整還原。
• 情境切換：scenario 控 empty / mixed / has-high-engagement / detail-timeline / tag-manage / favorite-limit / member-readonly；roleCode 控角色權限呈現。
• Mock 視覺：avatar 用可顯示 URL、中文姓名與 headline，Timeline 用真實感時間（避免空白誤判）。

12. 實作備註

• 禁止事項：❌ 不定義最終 API；BR-030~038 已回寫 business-rules.md（v1.5.0 + ATS 收斂 v1.6.0）。
• 注意事項：
  • recruitment CSS profile。
  • 聚合鍵 = 求職者（已裁決）（跨職缺合併為一列），與 104「誰來看我 / 應徵名單」拆裂模型明確不同——RD 僅評估 migration 實作方式，不需再確認方向。
  • debounce / 熱度為後端寫入管線責任，前端只渲染聚合結果與 Timeline。
  • 隱私：人才顯示姓名 / 履歷的可見程度需依平台隱私與履歷公開狀態（與既有人才搜尋一致）。

12.1 四致性表

欄位對照表

常數表

事件字典

一致性檢查：talent_interaction_recorded 為唯一互動事件名，view/save/apply 以 type 區分，不另立同名不同 payload 事件。

術語字典

12.2 版本凍結表

12.3 PRD 問題清單

12.4 Migration / 相容性

• 觸發：本功能改變「人才互動資料的查詢與聚合方式」（從拆裂 → 以求職者為鍵聚合，已裁決），屬「影響既有資料查詢/join」的情況（gen-prd Rule 22）。
• 建議策略：
  • 既有 view/apply 紀錄 backfill 成 TalentInteraction，並建立聚合列。
  • 聚合為「讀取時計算」或「寫入時維護物化列」由 RD 依效能選擇；本 PRD 不鎖定。
  • rollback：保留原拆裂查詢入口至新視圖穩定。

13. 下一步

• 以求職者為聚合鍵已裁決；RD 評估 migration 實作方式（讀時計算 vs 物化列）。
• 與 pm_44 對齊 BR-027 #3 排除封鎖求職者（blocking）。
• （收藏/標籤已裁決免費；付費鉤子改為熱度洞察/進階分析，另案評估）。
• gen-storybook-mockup-gen 產出 mockup（recruitment profile）+ TalentRow/InteractionTimeline/TagChip isolation。
• Coda：新增列 企業人才 CRM（收藏＋標籤＋訪客時間軸），PRD 欄＝pm_45（review 後執行）。

文件結束