Admin 公司列表「公司頁完成度」PRD（給後端 API 規格產生器使用）

產出 persona：CEO with PM Background。
目標 repo：W101-Admin-Web（incremental；不產 Storybook，Admin local 實作即可）。
關聯：pm_38（公司資料完成度三桶／BR-014）、business-rules.md BR-014／BR-006。

1. 文件資訊

• 文件類型：需求規格書（Admin 後台 incremental；無 Storybook mockup）
• 適用對象：前端（Admin-Web）、後端、產品、QA、客服營運
• 最後更新：2026/08/11
• 版本：1.1.0
• PRD 識別碼：pm_50
• 對應 Storybook：N/A（本次明確不做 Storybook）
• Storybook（local-prd）：N/A — 以本 PRD 為 SoT；實作於 Admin local
• Storybook（online）：N/A
• 文件入口（建議）：doc/feature/pm_50/admin-company-profile-completeness-prd.md
• 建立日期：2026/08/07
• 目標路由：https://admin.wport.me/members/companys
• 公開頁連結格式：https://wport.me/company/{enc_id}（新視窗）

1.1 修訂紀錄

2. 開發進度與設計來源

開發進度

• 前端 PR #（W101-Admin-Web）：TBD
• 後端 PR #（W101-AMS）：TBD

後端歸屬：Admin 列表 API 在 W101-AMS（company/v2），非 W101-TalentSearchHub；完成度規則的權威實作在 TSH（見 ADR-001）。

設計來源

• Figma：N/A（內部小需求，沿用既有 Naive UI Table／Form）
• 既有 FE（incremental）：
  • W101-Admin-Web/src/views/members/company/index.vue
  • W101-Admin-Web/src/views/members/company/columns.ts
  • W101-Admin-Web/src/api/members/company.ts → GET /company/v2/search
• 完成度語意對照：pm_38 Storybook CompanyEditCompletenessChecklist.vue（Logo／基本資料／公司介紹 → n/3）
• 不做 Storybook：Admin 頁面僅內部使用，local 直接改即可

3. 模擬頁面摘要

3.1 功能概述

• 功能名稱：Admin 公司列表 — 公司頁完成度
• 主要使用者角色：WPort 內部客服／營運（Site Admin；Admin 本就僅內部，不另加權限）
• 核心目標：
  • 活動（如台大創創）或外部呼叫公司頁時，客服可在後台一眼判斷「能不能被搜尋／公開看到」、是否缺 Logo
  • 避免前後台來回搜尋公司名稱才能確認可見性
  • 以 n/3 與 hover 缺項，加速催補不完整公司資料

3.2 範圍界定

v1（必含）

• 公司列表「開通狀態」後方新增「公司頁完成度」欄，顯示 0/3｜1/3｜2/3｜3/3
• Hover：首行顯示可見性結論（可被搜尋／不可被搜尋＋原因）；其下顯示三項完成狀態（公司 Logo、公司介紹、公司資料）；有 Logo 時顯示縮圖；有介紹時顯示摘要（過長截斷）
• 僅 可公開可見 者為超連結，點擊以新視窗開啟 https://wport.me/company/{enc_id}；不可見者（含 3/3 但未開通／已停用）顯示灰字不可點（見 ADR-007）
• 上方搜尋 bar 新增「公司完成度」下拉：0/3、1/3、2/3、3/3（與列表文案一致）
• 後端：Admin 列表 API 回傳完成度摘要；計算邏輯與 pm_38／BR-014 三桶一致；不讓 Admin FE 直接呼叫前台 employer profile-completeness API

Out of scope

• ❌ Storybook mockup
• ❌ 前台企業編輯頁／註冊精靈改版
• ❌ 後台一鍵通知 Owner 催補
• ❌ 修改 BR-014 判定規則本身
• ❌ 另建 Admin 專屬權限欄位（Admin 僅內部）

3.3 成功條件

• 客服在 /members/companys 不需切去前台搜尋，即可判斷公司是否可被看見（n/3 判斷資料補齊與否，hover 首行判斷是否真的可被搜尋）
• 可依完成度篩選列表，快速列出未完成公司
• 可見者一鍵開公開頁；不可見者不可點、無死連結

4. 商業規則對齊

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

4.2 補充說明

• 完成度 ≠ 開通／認證狀態：開通狀態（既有欄）與公司頁完成度（本功能）並列；認證通過但 0/3–2/3 仍可能公開頁 404／不可搜尋（對齊 BR-014）。
• ⚠️ n/3 不等於可見性：n/3 僅代表企業端可自行補齊的資料完整度（三桶七欄），不代表公司可被搜尋／公開可見。可被搜尋另需同時滿足：已開通（審核通過）、公司啟用、未刪除、所屬產業類別仍啟用。故 3/3 但搜不到是穩定可重現的情形，非資料競態。
  • 反向為真：可被搜尋 ⇒ 必為 3/3；但 3/3 ⇏ 可被搜尋。
  • 因應決策見 ADR-007（n/3 維持純資料完整度、可見性獨立表達）。
• 三桶定義（與 pm_38 checklist 對齊）：

• done_count = 完成桶數；顯示 {done_count}/3；profile_complete（BR-014 全滿足）時必為 3/3。
• 不新增 BR：僅 Admin 呈現既有規則結果。

4.3 衝突檢查

無硬衝突。本功能為 Admin 唯讀呈現＋篩選，不改變 C 端搜尋／公開頁 gate。

5. 資料實體與欄位

Rule 31：描述需追蹤的資料與用途，不鎖死最終 JSON／DB schema。命名供 Admin FE／Spec 對齊參考。

5.1 實體列表

5.2 語意欄位（參考介面，非最終 API）

/** Admin 列表列擴充：完成度摘要（由 BE 依 BR-014 三桶計算） */
interface CompanyProfileCompletenessSummary {
  done_count: 0 | 1 | 2 | 3;
  /** 顯示用字串，固定 "0/3" | "1/3" | "2/3" | "3/3" */
  label: '0/3' | '1/3' | '2/3' | '3/3';
  items: {
    logo: boolean;   // 公司 Logo
    intro: boolean;  // 公司介紹
    basic: boolean;  // 公司資料（名稱+產業+電話+地區+地址）
  };
  /** hover 可選：有值才顯示 */
  logo_url?: string;
  intro_excerpt?: string; // 截斷後摘要；無介紹則省略
}

/** 篩選參數（搜尋 bar） */
type CompletenessFilter = '0/3' | '1/3' | '2/3' | '3/3' | null; // null = 不限

5.3 容量／限制

6. 畫面區塊與資料需求

6.1 區塊列表

6.2 各區塊資料需求

SEC-FILTER 搜尋 bar

• 欄位：公司完成度（NSelect）
• 選項：0/3、1/3、2/3、3/3（可清空＝不限）
• 行為：與既有篩選相同——按搜尋／submit 後帶入 getCompaniesData；不另做權限；URL query 行為對齊現況（現況僅 uniform_number／name 從 query 回填，完成度篩選與 status 等欄位一樣僅活在表單＋請求參數）

SEC-LIST 公司列表欄

• 位置：columns.ts 中「開通狀態」之後
• 顯示：n/3
• 可見者：可點連結樣式；不可見者（含 3/3 但未開通／已停用）灰字純文字
• 資料：列表 API 每列附帶 CompanyProfileCompletenessSummary（避免 N+1）

SEC-HOVER

• 首行：可見性結論——「✅ 可被搜尋」或「⚠️ 不可被搜尋：<原因>」。原因須涵蓋四種：尚未開通、公司已停用、資料未補齊（列出缺項）、所屬產業已停用（其中「產業已停用」僅後端算得出，Admin 列表無此資訊）
• 三項：完成／未完成（可用勾／叉或 Tag）
• 有 logo → 縮圖；無則該區顯示「未上傳」
• 有介紹摘要 → 顯示；無則「未填寫公司介紹」
• 元件建議 NPopover（需顯示 logo 縮圖；現有 columns.ts 無 popover 前例）

SEC-LINK

• URL：https://wport.me/company/{enc_id}
• 新視窗；不可見者不渲染 <a>（ADR-007）

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

8. API Hints（非最終 API 設計）

8.1 Read

• HINT-GET-1：Admin 公司列表擴充完成度

  • 對應：SEC-LIST／SEC-FILTER
  • 既有：GET /company/v2/search（Admin）
  • 擴充輸出（每列）：完成度摘要（done_count／label／三桶 boolean；可選 logo_url、intro_excerpt）
  • 擴充輸入：完成度篩選（精確匹配 0/3…3/3）
  • 判定：與 pm_38／BR-014 三桶語意一致（實作方式見 ADR-006）；禁止 Admin FE 直打前台 employer path
  • 可見性：每列另需可見性結論與不可見原因（§6.2 SEC-HOVER 四種原因），其中「所屬產業已停用」僅後端算得出
  • 效能：列表一次回傳；禁止對每列另打 completeness
  • 篩選正確性：完成度篩選須在查詢層完成；不得以事後過濾實作，否則總筆數與分頁會不一致

• HINT-GET-2（可選）：單公司 detail 帶完成度

  • 若編輯 Modal 日後需要可複用同一摘要；v1 非必須

8.2 Write

• N/A（本功能無寫入）

8.3 Auth／合約最小集

9. 導航／交付 Map

• Storybook：N/A（本次不做）
• Production（Admin）：/members/companys
• 公開頁：https://wport.me/company/{enc_id}
• 驗收方式：Admin local／staging 列表＋篩選＋連結

10. Flowcharts

10.1 User Flow

flowchart TD
    A[客服開啟 /members/companys] --> B[檢視列表完成度 n/3]
    B --> C{需要篩選?}
    C -- 是 --> D[搜尋 bar 選 0/3～3/3]
    D --> E[重查列表]
    C -- 否 --> F[Hover 看三項缺什麼]
    E --> F
    F --> G{是否可被搜尋?}
    G -- 是 --> H[新視窗開公開頁]
    G -- 否 --> I[不可點；hover 顯示原因<br/>資料未補齊→催企業；未開通/已停用→內部處理]

10.2 System Flow

sequenceDiagram
    participant CS as 客服
    participant AdminFE as Admin-Web
    participant AdminAPI as Admin API
    participant Domain as Completeness Service<br/>(共用 BR-014 三桶)

    CS->>AdminFE: 開啟／搜尋公司列表
    AdminFE->>AdminAPI: GET /company/v2/search<br/>(含 completeness 篩選)
    AdminAPI->>Domain: 批量計算三桶
    Domain-->>AdminAPI: summary per company
    AdminAPI-->>AdminFE: 列表 + 完成度摘要
    AdminFE-->>CS: 顯示 n/3；Hover 可見性結論＋三項
    alt 可被搜尋
        CS->>AdminFE: 點連結
        AdminFE-->>CS: window.open wport 公開頁
    else 不可被搜尋
        Note over AdminFE: 灰字純文字，無連結<br/>hover 顯示原因
    end

10.3 Navigation

flowchart LR
    AdminList["Admin 公司列表"] -->|"僅可見者，新視窗"| PublicPage["wport 公司公開頁"]

10.4 Edge Case Coverage

11. Mock Data Schema

• 本次無 Storybook：不強制 mock schema。
• Admin 本機開發：可用 mock 列表列附帶 completeness；情境覆蓋 0/3–3/3 各至少一筆。

12. ADR（架構決策紀錄）

ADR-001: Admin 擴充列表 API，不直打前台 completeness API

• Status: Superseded by ADR-006（2026-08-11）——「不直打前台 API」「不 N+1」仍有效；「後端共用同一套計算 service」部分被取代
• Context: pm_38 規劃 GET /companies/{id}/profile-completeness 為企業端契約；Admin 為 site-admin＋/company/v2/*。列表若逐筆打會 N+1。
• Decision: 在 Admin GET /company/v2/search（必要時 detail）回傳完成度摘要；後端共用同一套三桶／BR-014 計算服務。
• Consequences: FE 實作單純；BE 需保證 Admin 與前台判定一致；禁止 Admin FE 呼叫 employer path。
• Decision maker: Eric | Date: 2026-08-07

ADR-002: 完成度 UI 用三桶 n/3，非七欄逐列

• Status: Accepted
• Context: BR-014 有七項；客服需要掃列表速度。pm_38 編輯頁 checklist 已收斂為 Logo／基本資料／介紹。
• Decision: Admin 顯示與篩選一律 0/3–3/3；三桶定義對齊 pm_38 checklist。
• Consequences: 與企業編輯 checklist 語意一致；細節缺哪一基本欄位需 hover「公司資料」未完成後再進編輯 Modal 細看（v1 可接受）。
• Decision maker: Eric | Date: 2026-08-07

ADR-003: 篩選／URL 行為對齊既有公司列表

• Status: Accepted
• Context: 現況僅 uniform_number／name 從 route query 回填；其餘篩選活在表單。
• Decision: 完成度篩選與 status 等欄位相同，不強制新增 URL sync。
• Consequences: 實作成本低；分享連結不含完成度篩選（內部可接受）。
• Decision maker: Eric | Date: 2026-08-07

ADR-004: 僅 3/3 可開公開頁（新視窗）

• Status: Superseded by ADR-007（2026-08-11）——「不給死連結」的意圖保留；「以 3/3 為判準」被取代
• Context: 未 profile_complete 時公開頁 404／不可搜尋；未滿 3/3 給連結會誤導。
• Decision: 只有 3/3 渲染連結 → https://wport.me/company/{enc_id} 新視窗；未滿純文字。
• Consequences: 無死連結；客服對「可見」有明確操作驗證路徑。
• Decision maker: Eric | Date: 2026-08-07

ADR-005: 不做 Storybook

• Status: Accepted
• Context: Admin 僅內部；需求為既有頁 incremental。
• Decision: 不產 Storybook；以本 PRD + Admin local 驗收。
• Consequences: 無雙 URL Storybook 連結；§9 標 N/A。
• Decision maker: Eric | Date: 2026-08-07

ADR-006: 完成度計算不共用 service，AMS 各自實作＋一致性測試釘住

• Status: Accepted
• Supersedes: ADR-001（僅取代其「共用 domain service」部分）
• Context: ADR-001 假設兩端可共用同一套計算。實查後：Admin 列表 API 在 W101-AMS（company/v2），完成度規則的權威實作在 W101-TalentSearchHub；兩個 repo 沒有共用 domain 層——僅共用 npm 套件 w101-lib-db，其內容為資料庫連線、base repository、分頁型別，不含 entity 與業務邏輯，entity 兩邊各自複製維護。AMS 目前也完全沒有完成度相關實作。原決策在現行架構下無法執行。
• Decision: 由 AMS 自行實作三桶計算，以測試釘住與 TSH 權威規則逐項一致；規則語意以本 PRD §4.2 為 SoT。共用套件（如公司 domain lib）列為 v2 選項，不擋本次。
• Consequences: 兩處實作有漂移風險，須以一致性測試防守；未來 BR-014 若異動，兩端都要改（測試會擋住只改一邊）。
• Alternative rejected: 新建共用套件——本次為單一 Admin 欄位需求，為此拉出跨 repo 套件成本與風險不成比例。
• Decision maker: Eric | Date: 2026-08-11

ADR-007: n/3 維持純資料完整度；可見性獨立表達，僅可見者給連結

• Status: Accepted
• Supersedes: ADR-004
• Context: ADR-004 假設「3/3 ⇒ 公開頁可見」。實查後不成立：前台公司搜尋除七項資料完整度外，另有 已開通（審核通過）、公司啟用、未刪除、所屬產業仍啟用 四道條件。一家 3/3 但未開通的公司會穩定搜不到，照原設計會給出連結，使客服誤判「這家看得到」——正與 §3.1 核心目標「一眼判斷能不能被搜尋」相違。
• Decision:
  1. n/3 不納入開通／啟用等狀態，維持純「企業端可自行補齊的資料完整度」；
  2. 可見性以獨立維度表達：hover 首行給結論與原因、連結僅在可見時渲染；
  3. 不可見原因涵蓋四種：尚未開通、公司已停用、資料未補齊、所屬產業已停用。
• Consequences: 無死連結、無誤判；n/3 與 pm_38 企業端 checklist 維持同一數字，催補用途不受污染；後端需多判「產業是否啟用」（Admin 列表原本無此資訊）。
• Alternative rejected: 把狀態併入 n/3 分母——會使客服看到 2/3 卻不知是資料缺還是沒審核，催錯對象；且同一家公司在企業端與 Admin 顯示不同數字。
• Decision maker: Eric | Date: 2026-08-11

13. 實作備註

• 禁止：
  • ❌ Admin FE 直打前台 employer completeness API
  • ❌ 列表 N+1 打單筆完成度
  • ❌ 修改 BR-014／公開頁 gate 行為
  • ❌ 本 PRD 鎖死最終 JSON field 名（由 OpenAPI Spec 定）
• 注意：
  • 欄位插在「開通狀態」之後（columns.ts）
  • 文案列表與篩選一致：0/3–3/3
  • 三桶計算須與 pm_38 checklist／BR-014 一致（ADR-002／006）
  • n/3 與可見性是兩件事：連結可點性依可見性，不依 n/3（ADR-007）
  • 完成度篩選須在查詢層完成，不得事後過濾——否則總筆數與分頁不一致
  • Migration：既有公司無新持久欄亦可（計算欄／查詢時衍生）；若 BE 為效能加存 done_count 冗餘欄，須與寫入公司時重算一致（RD 可選）

13.1 一致性表（Stage 5／6）

Field mapping

Constants

Event dictionary

v1 分析事件非 blocking；可不實作。

Terminology

Version freeze

13.2 PRD 問題清單

13.3 Sync-fix list

14. 下一步

1. BE／FE 依本 PRD 實作於 W101-Admin-Web + Admin API
2. Staging：篩選四態、hover（含可見性結論四種原因）、僅可見者可開公開頁
3. （可選）效能：若列表過慢再評估冗餘 done_count 欄

文件結束