公司資訊編輯、公司註冊 2.0 Mockup PRD（給後端 API 規格產生器使用）

此範本專門給 30%-feature-gen 產出的 mockup PRD 使用。 backend-api-spec-generator 會讀取這份文件與 Storybook mockups 來產生後端 API 規格。

1. 文件資訊

• 文件類型：Mockup 需求規格書（前後端共用視圖）
• 適用對象：前端開發、後端開發、產品、QA
• 最後更新：2026/07/08
• 版本：1.6.0
• PRD 識別碼：pm_38
• 對應 Coda rowId：i-ZHiJ-arBOE
• 對應 Storybook：storybook/src/stories/mockups/company/CompanyEditRegisterV2.stories.ts
• Storybook 連結：https://storybook.wport.me/?path=/docs/mockups-company-companyeditregisterv2—docs
• 文件入口（網頁版）：https://prd.wport.me/pm_38/company-edit-register-v2/
• 建立日期：2026/05/15

1.1 修訂紀錄

1.5 工程師回饋裁決（company-review 回應，2026/06/24）

以下為針對工程師 company-review 回饋及 §13.8 / §13.9 盤點之 PM 裁決，優先於本文後續較舊敘述； backend-api-spec-generator 請以本節為準。 每筆裁決須含「為何」——避免 RD 只知結論、不知取捨理由。

註：TW 統編查詢查詢順序以 D1 為準：GCIS live → 稅籍資料集 fallback → 皆無則手動註冊。本文「商工登記／GCIS」指第一順位來源；「稅籍資料集」指第二順位。

2. 開發進度與設計來源

Mockup 交付策略（本次）

• 本 PRD 的 Storybook mockup 採 copy-first 1:1 快照策略（先依當下 production 畫面 1:1 複製，再做需求增量）。
• 此 mockup 用途為 本次前後端需求對齊；正式功能上線後不承諾長期與 production 持續同步。
• 為避免影響正式站，mockup 變更僅限 storybook/，不直接改動 production 元件行為。

開發進度

• 前端 PR #：TBD（待 Storybook mockup 完成後排程）
• 後端 PR #：TBD（API 規格由 OpenAPI Spec 產出後排程）

設計來源

• Figma 連結：待補（建議建立 Company 2.0 design file）
• 既有 FE 參照：
  • 公司快速註冊 Storybook：storybook/src/mockupcomponents/company/MockupCompanyQuickRegisterPage.vue
  • 公司編輯頁（incremental 基準）：production FE，未在 Storybook 建立 baseline，本次將以 storybook-mockup-gen 補上基準頁，再以 diff 視覺化新增區塊
• SaaS Benchmark：
  • LinkedIn Company Page（cover image 1128×191、影片貼文、milestones）
  • 104 公司頁（簡介、影片、福利、得獎、里程碑、員工心聲）
  • CakeResume Company Profile（cover、影片、mission、milestones、awards）
  • Wellfound（cover、影片、mission、team highlights）

3. 模擬頁面摘要（Mockup Summary）

3.1 功能概述

• 功能名稱：公司資訊編輯、公司註冊 2.0
• 主要使用者角色：Employer（Owner / Admin）；Manager 不可編輯公司資訊（依 BR-016）
• 核心目標：
  • 提升公司頁面資料準確度（透過商工登記公示資料 API 自動帶入）並減少人工填寫
  • 強化公司品牌呈現能力（Banner + 影片 + 痛點/得獎/里程碑），縮短求職者決策距離
  • 提供企業對欄位（資本額、負責人、設立日期、董監事）的「顯示/隱藏」控制權；資本額預設不公開，其餘預設公開（D15）。電話、地址、員工人數恆常公開（D15，延續既有 WPort）
  • 平衡註冊轉換與 C 端信任（D22）：維持現行 Step 1 建立公司；新增 profile_complete gate 控制 C 端可見性；職缺上架仍由 BR-005 gate

3.2 範圍界定

v1（必含，本次交付）

• 公司註冊流程：
  1. 先選「公司註冊國家/地區」（可搜尋下拉，必填，/v2/api/countries/supported，v1 僅 TW/VN/TH；見 D7）→ 再輸入登記號碼：
     • TW：8 碼統一編號 → GCIS live 優先，查無則 稅籍資料集 fallback（D1）
     • VN：10 或 13 碼 MST（稅籍編號） 必填；格式驗證 FE+BE（D23）
     • TH：13 碼 DBD 法人登記號碼（MOA） 必填；格式驗證 FE+BE（D23）
     • TW 命中則帶入公司名稱、資本額、負責人、地址、設立日期；雙源皆無仍可註冊（見 D1）。Step 1「下一步」即建立 draft 公司（D22）
  2. 公司頁（Step3）：Logo 上傳區塊強化顯示；允許暫不上傳進入下一步（D17），但顯示完成度提示：「上傳 Logo 後才可被求職者於公司搜尋找到」
  3. 公司頁頂部新增 Banner 上傳
  4. 公司介紹區改為最多 3 個介紹影片 URL（0–3 彈性；v1 無獨立照片欄，見 D11）
  5. 「其他福利」下方新增 4 個 free text 區塊：痛點、得獎、里程碑、QA（可折疊）
  6. 統編驗證通過後該欄位鎖定，不可修改（見 D10）
• 公司編輯頁（incremental）：
  1. 公司基本資料區：先「公司註冊國家/地區」再統編（D7）；derived 欄位可手動覆寫 + 重新拉取
  2. 公司頁：Banner 上傳、Logo 上傳強化（完成度 gate，見 D17）、介紹區 3 組 URL、福利區下方四區塊（含可折疊 QA）
  3. 新增「公司介紹影片」URL 連結欄位（最多 3 個，0–3 彈性；支援 YouTube / Vimeo；與介紹區合併呈現）
  4. 統一編號顯示於公司頁面（管理頁 + 公開頁）
  5. 新增 3 個新欄位：設立日期、負責人、董監事，每個欄位均有「不顯示」勾選（電話、地址、員工人數不提供隱藏開關，見 D15）
  6. 「其他福利」下方新增 4 個選填 free text 區塊：解決的痛點、得獎資訊、里程碑、QA（可折疊）

Nice-to-have（v2，本次不交付）

• 影片 oEmbed 預覽縮圖、自動抓 metadata
• 員工心聲、福利圖示化
• 公司資料變更歷史審計
• Banner / Logo 智能裁切
• 統編 API 失效時的人工申訴流程

Out of scope

• 跨國法遵深度客製（V Card / 國際統編等）
• 公司資料 GDPR 級別匯出
• 公司頁面 SEO 結構重構（已有 pm_33）
• 統編以外的政府資料源整合

3.3 成功條件

4. 商業規則對齊（Business Rules Alignment）

供 backend-api-spec-generator 對齊 prd/business-rules.md。 新功能若有新規則，先在此描述，再視情況回寫至 business-rules。

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

4.2 補充說明（新規則 / BR 更新建議）

新規則建議（待 BR 更新）：

• 公司 Lifecycle（D22；建議納入 business-rules 或 API 層文件）

  • 狀態欄位：lifecycle_status：draft | profile_complete
  • draft：Step 1 POST /companies 建立；B 端可續填、可建職缺草稿；C 端不出現於公司搜尋（BR-006/014）、公開頁 API 回 404
  • profile_complete：BE 依 BR-014 全欄位判定為 true 時自動設定（含 Logo）；方可出現於公司搜尋、公開頁可開
  • 職缺上架：仍須 BR-005 公司認證（與 lifecycle_status 獨立）；發布職缺時若未 profile_complete → 導向公司編輯補齊；若未通過 BR-005 → 導向驗證上傳
  • BR-022：draft 計入每帳號 10 間上限
  • 清理：lifecycle_status=draft 且 updated_at 超過 30 天 → BE 排程硬刪除（連同無職缺之空殼）；有職缺草稿者不自動刪（改為標記待清理／通知 Owner，[RD 可細化]）
  • 完成度 API：GET /companies/{id}/profile-completeness 回傳 BR-014 各欄位是否已填 + missing_fields[]（供 FE checklist）

• BR-024（建議新增）：統一編號驗證後不可變更

  • 描述：透過商工登記公示資料 API 驗證通過的統編，於該公司生命週期內不可修改
  • 適用範圍：所有透過 v2 註冊流程建立或編輯時補登的公司
  • 變更途徑：僅限後台人員（人工審核）介入，且需留下審計記錄
  • UI 影響：統編欄位於驗證通過後顯示為唯讀（不顯示統編驗證徽章，見 D20）
  • 理由（Why）：避免企業透過自助修改規避稅務／法遵驗證；對齊 BR-005 公司驗證精神
  • 補充：API 帶入的衍生欄位（公司名稱、資本額、負責人、地址、設立日期）允許企業點按「重新拉取」更新（資料源來自政府公開資料，本身為事實）
  • 國家鎖定：tax_id_locked=true 時，country_code 不可變更（後端拒絕；如需調整須聯繫客服人工處理）

• BR-025（建議新增）：公司欄位顯示偏好（Field Visibility Preferences）

  • 描述：企業可控制以下欄位是否對外（公司公開頁）顯示——僅此 4 欄：
    • 資本額（is_capital_amount_visible）
    • 設立日期（is_establishment_date_visible）
    • 負責人（is_representative_visible）
    • 董監事（is_directors_visible）
  • 不納入本規則（恆常公開、無開關，見 D15）：聯絡電話（phone）、公司地址（address）、員工人數（employee_count_range_code）——延續既有 WPort，v2 不新增隱藏能力
  • 預設值（D15）：
    • 資本額 → 預設不顯示（false）
    • 設立日期、負責人、董監事 → 預設顯示（true）
  • Migration（D14）：既有已勾「不顯示」者原樣保留；v2 新增三欄（負責人/設立/董監事）無歷史值 → 顯示；資本額無歷史值 → 不顯示
  • 適用範圍：公司公開頁（C 端）；公司管理頁（B 端內部）永遠顯示
  • 與 BR-014 之關係：顯示偏好不影響「公司搜尋顯示條件」的資料完整度判定（資料層存在即視為填寫，不影響搜尋曝光）
  • 理由（Why）：降低企業對公開敏感資訊的填寫抗拒；非隱私保護（政府公開資料仍可他處查得）

4.3 ⚠️ 衝突檢查結果

無硬衝突。BR-005（公司驗證需文件）與本功能「統編 API 帶入」屬於不同流程：

• 統編 API 帶入：自助、即時、用於資料初始化
• 公司驗證：人工審核、需上傳 PDF、用於職缺上架資格
• Lifecycle 分層（D22）：draft（早建立）→ profile_complete（BR-014，C 端可搜尋）→ BR-005 公司認證（職缺可上架）
• 統編 API 帶入為資料初始化；求職者端信任以 BR-005 公司認證為準（上架職缺必須通過）。v1 不另顯示統編驗證徽章（D20）

4.4 市場 rollout 決策（v1，2026-06-22 確認）

原則：註冊國家 = 平台承諾能完整服務的市場清單，不是全球 ISO 國家表。
選項由後端 /v2/api/countries/supported 白名單驅動；FE 不 hardcode 全量國家。

4.4.1 已支援市場（Supported Markets）

• 註冊 / 編輯下拉：僅顯示上表三國（D21）。
• 不開放全球：印尼、新加坡、日本等不在 v1 註冊選項；本期不處理白名單以外國家註冊，不另做 waitlist／留 email 出口。待審核 SOP、幣別、客服、職缺曝光链路 ready 後，由 BE 擴白名單即可，無需改 DB schema。

4.4.2 非台灣：tax_id / 公司登記號碼行為

TW 統編查詢瀑布（D1）：

checksum 通過 → ① GCIS live API
              → ② 若 GCIS 查無／失敗：全國營業稅籍登記資料集（本地）
              → ③ 雙源皆無：found=false，允許手動填寫並完成註冊（tax_id_verified=false）

已移除（v1.6）：非 TW 且未填 → 選填；VN/TH 自 v1.6 起改為必填（D23）。

tax_id_verified × tax_id_locked 狀態表（D10 定案）：

• 統編唯一性（D3）：認證前多帳號可共用同一統編；公司認證通過後一統編一公司；validate-uniform-number 僅擋已認證占用 + 審核防重
• 資料帶入：derived 欄位**僅在 TW + 查詢成功（GCIS 或稅籍）**時於 Step3 帶入；非 TW 手動填寫
• Step2 成功提示：TW 統編查詢成功僅顯示 inline「✓ 查詢成功，資料將帶入公司頁」，不在 Step2 展開 derived 編輯區（不掛統編驗證徽章，D20）。
• 重新拉取：編輯頁「重新拉取最新登記資料」按鈕僅在 country_code = tw 時顯示。

4.4.3 聯絡電話與 country_code 連動

• v1 不開全球國碼表：聯絡電話國碼下拉僅 +886 / +84 / +66，與 supported markets 一致。
• 預設連動：使用者選擇「公司註冊國家/地區」後，國碼預設帶入對應值（仍可手動改，但僅限三選一）。
• 電話類型：維持既有 mobile / landline 下拉；預設 landline（市話）；格式驗證依 country_code + dial_code 規則表（BE 為 SoT）。
• 與 BR-014：電話、地址須存在以符合搜尋曝光；二者恆常公開（D15），無 visibility 開關

4.4.4 tax_id 格式規則表（三國；D23）

原則：三國共用 tax_id 欄位；country_code 決定 label、placeholder、驗證規則與儲存格式。
FE 與 BE 必須實作相同規則（Storybook 參考：storybook/src/utils/company-tax-id.ts）；POST /companies 非法格式回 422 + error_code: TAX_ID_INVALID_FORMAT。
VN/TH 僅格式驗證，不設 tax_id_verified／不 lock；真實性由 BR-005 文件 + iCan 人工審核（D4）把關。

三國碼數一覽

泰國說明（th）

• 此號碼為泰國商業發展部（Department of Business Development, DBD）核發的法人登記號碼（Memorandum of Association Number, MOA）。
• 在泰國實務上，此 13 碼號碼通常也作為法人稅籍號（Taxpayer Identification Number, TIN）使用（多數有限公司兩者同號）。
• v1 驗證採 MOA 規則：第 1 碼須為 0（有限公司），第 13 碼為 checksum；拒絕自然人 13 碼身分證（PIN）誤填。
• 合夥企業（第 1 碼 1–3）格式待 iCan 確認後 v1.1 擴充；不符 MOA 者仍可走 BR-005 文件人工審核。

越南說明（vn）

• MST（Mã số thuế）自 2021 企業登記改革後，與企業識別號碼合一，作為稅籍與社保識別碼。
• 10 碼：獨立法人／總公司（N1N2 省份碼 + 7 碼序號 + 第 10 碼 checksum）。
• 13 碼：分公司／分支機構（10 碼母體 + - + 001–999）；輸入可含連字號，儲存為 13 碼 compact。

驗證規則（演算法 SoT：python-stdnum 同等邏輯）

錯誤碼（FE / BE 共用）

5. 資料實體與欄位（Data Entities & Fields）

依 Rule 30：本節描述「需要追蹤什麼資料、為什麼」，不勾選 API JSON 命名 / 加密策略 / DB schema。實際 API/DB 由 OpenAPI Spec（RD 負責）決定。 欄位命名僅供 Storybook TypeScript 介面參考，最終以 Storybook mockup 為準。

5.1 實體列表

5.2 實體欄位定義（TypeScript 介面，僅供 Storybook 參考）

// 公司主體（擴充欄位；既有欄位不重複列）
interface CompanyV2 {
  enc_id: string;

  // —— Lifecycle（D22）——
  lifecycle_status: 'draft' | 'profile_complete';
  profile_complete: boolean;              // BE 依 BR-014 計算；與 lifecycle_status 同步

  // —— Step 1 建立 draft 必填 ——
  name: string;
  country_code: string;                   // 公司註冊國家/地區（小寫 tw/vn/th；**先於**統編選擇；supported markets only）
  phone: string;                          // 聯絡電話（Step 1）
  tax_id: string;                         // 三國皆必填（D23）；TW：8 碼統編；VN：MST 10/13 碼；TH：DBD MOA 13 碼
  tax_id_verified: boolean;               // GCIS 或稅籍資料集驗證通過
  tax_id_verified_at?: string;            // 驗證時間
  tax_id_locked: boolean;                 // 驗證通過後 true → FE 唯讀

  // —— profile_complete 必填（BR-014；含於註冊後續步驟或編輯頁補齊）——
  logo_url?: string;                      // draft 可空；profile_complete 時必填
  intro: string;
  // industry_category_codes[]、area_codes 等 BR-014 欄位（既有 schema，略）

  // —— 商工登記公示資料帶入欄位（derived，允許重新拉取）——
  capital_amount?: number;                // 資本額
  representative_name?: string;           // 負責人
  registered_address?: string;            // 登記地址
  establishment_date?: string;            // 核准設立日期 (YYYY-MM-DD)
  directors?: string[];                   // 董監事（陣列，名單）

  // —— 既有可編輯欄位 ——
  // intro 已列於 profile_complete 區
  // ... (其他既有欄位省略)

  // —— 新增：自訂 Banner ——
  banner_url?: string;

  // —— 新增：介紹影片（最多 3 個）——
  video_links?: CompanyVideoLink[];

  // —— 新增：欄位顯示偏好（對應 BR-025）——
  field_visibility: CompanyFieldVisibility;

  // —— 新增：4 個選填區塊（痛點/得獎/里程碑/QA）——
  pain_points?: CompanyPainPoint[];       // 解決的痛點
  awards?: CompanyAward[];                // 得獎資訊
  milestones?: CompanyMilestone[];        // 里程碑
  qa_items?: CompanyQaItem[];             // Q&A（可折疊）
}

interface TaxIdLookupResult {
  tax_id: string;
  found: boolean;                         // 是否查到（GCIS 或稅籍任一命中即 true）
  company_name?: string;
  capital_amount?: number;
  representative_name?: string;
  registered_address?: string;
  establishment_date?: string;
  directors?: string[];
  raw_source?: 'gcis_open_data' | 'tax_registry_dataset';  // D1：標示命中來源
  fetched_at: string;
  // 例外時的回傳
  error_code?: 'NOT_FOUND' | 'INVALID_FORMAT' | 'API_DOWN' | 'RATE_LIMITED';
  error_message?: string;
}

interface CompanyVideoLink {
  url: string;
  provider: 'youtube' | 'vimeo' | 'other';
  video_id?: string;                      // 由 URL 解析
  title?: string;                         // oEmbed 抓取（v2 才做）
}

interface CompanyFieldVisibility {
  is_capital_amount_visible: boolean;     // 預設 false（D15）
  is_establishment_date_visible: boolean; // 預設 true
  is_representative_visible: boolean;     // 預設 true
  is_directors_visible: boolean;          // 預設 true
  // phone / address / employee_count：無 visibility 欄位（D15，恆常公開）
}

interface CompanyMilestone {
  year: number;                           // 例：2018
  title: string;                          // 例：「A 輪募資完成」
  description?: string;
  display_order: number;                  // 拖曳排序（D13）；預設可依 year 升冪
}

interface CompanyAward {
  year: number;
  name: string;                           // 獎項名稱
  issuer?: string;                        // 頒發單位
  description?: string;
  display_order: number;                  // 拖曳排序（D13）；預設可依 year 降冪
}

interface CompanyPainPoint {
  title: string;
  description: string;
  display_order: number;                  // 拖曳排序（D13）
}

interface CompanyQaItem {
  question: string;
  answer: string;
  display_order: number;                  // 拖曳排序（D13）；預設依輸入序
}

5.3 容量限制（必記）

6. 畫面區塊與資料需求（UI Sections & Data Needs）

6.1 區塊列表

6.2 各區塊資料需求

SEC-REG-1b 註冊精靈：公司註冊國家/地區

• 位置：公司基本資料表單內，先於統一編號 / 公司登記號碼欄位（D7）
• 元件：可搜尋下拉（Storybook mock：n-select + filterable；production：PrimeVue Select + filter）
• 驗證：必填
• 選項：/v2/api/countries/supported（v1 白名單：tw、vn、th）
• 預設：依使用者 IP／語系建議；台灣公司預設 tw
• 連動：變更國家 → 重設 tax_id 查詢狀態；更新電話國碼預設（見 SEC-REG-1c）
• 鎖定限制：若該公司 tax_id_locked=true（BR-024），禁止變更 country_code；後端拒絕並提示聯繫客服

SEC-REG-1 註冊精靈：統編 / 公司登記號碼

• 僅 country_code = tw 時：
  • 使用者輸入 8 碼統編 → 按「檢查可用性」→ 前端 checksum → BE 瀑布查詢（D1）：① GCIS live → ② 稅籍資料集 → ③ 皆無則 found=false
  • 可用性檢查（D3）：「檢查可用性」沿用 validate-uniform-number（is_available）；僅當該統編已被已認證公司占用時拒絕並引導加入既有公司；未認證前多帳號可共存，公司認證通過時確立唯一性
  • 查詢成功：Step2 inline「✓ 查詢成功，資料將帶入公司頁」；derived 於 Step3 帶入
  • 雙源皆無：允許手動填寫並進入 Step 1 建立 draft；tax_id_verified = false
• 非 TW（vn / th）（D23）：
  • 必填；label 依 §4.4.4（VN「稅籍編號（MST）」；TH「法人登記號碼」）
  • blur 與提交時 FE 執行 §4.4.4 checksum；BE POST /companies 重驗，非法回 422
  • 不顯示 GCIS 查詢 UI；不呼叫政府 API；tax_id_verified = false；不鎖定
  • TH tooltip 須說明：泰國商業發展部（DBD）核發的法人登記號碼（MOA），通常也作為法人稅籍號（TIN）使用；範例 0994000617721
  • VN 範例：0100233488（10 碼總公司）、0314409058-002（13 碼分公司）

SEC-REG-1c 註冊精靈：聯絡電話

• 國碼：+886（TW）、+84（VN）、+66（TH）；不開全球 ITU 表
• 預設：跟隨 country_code 自動帶入對應國碼
• 類型：mobile / landline（沿用既有）；預設 landline（市話）（D15）
• 驗證：依 country_code + 國碼 + 類型的 BE 規則表；FE 顯示對應 placeholder

SEC-REG-1d 註冊精靈：Step 1 建立 draft

• 觸發：Step 1（國家 + 統編/登記號 + 聯絡電話 + 公司名稱等基本欄位）按「下一步」
• API：POST /companies（見 HINT-MUTATION-1a）
• 必填：country_code、name、phone、tax_id（三國，§4.4.4 格式驗證）；可帶 derived overrides
• 回傳：201 + enc_id + lifecycle_status=draft
• 後端：依 country_code 驗證 tax_id 格式；僅 TW 執行 D1 瀑布重查（GCIS → 稅籍）→ 命中則 tax_id_verified=true 並鎖定
• FE：取得 enc_id 後後續步驟改走 PATCH /companies/{id}；使用者可離開後由公司列表續填

SEC-REG-2 註冊精靈：Logo 步

• 驗證：不禁用「下一步」；未上傳時顯示黃色提示條：「尚未上傳 Logo——完成後才可被求職者於公司搜尋找到」
• 上傳：走既有 upload → PATCH 寫入 logo_url
• 與 BR-006 關係：Logo 為 BR-014 / profile_complete 必要條件；BE 搜尋 API 硬擋，FE 以完成度 checklist 引導

SEC-EDIT-1 公司基本資料區（incremental）

• 顯示：統編欄位若 tax_id_locked=true → 唯讀（無徽章，D20）；旁邊「重新拉取最新登記資料」按鈕（更新 derived 欄位但不解鎖統編）
• 資料需求：當前 Company 全部欄位 + visibility flags

SEC-EDIT-2 自訂 Banner 區

• 互動：拖曳 / 點選上傳 → 顯示預覽（4.8:1 框）→ 「儲存」or「移除」
• 若失敗：顯示錯誤（容量超標、格式錯誤）
• 空狀態：「點此上傳 Banner，建議尺寸 1920×400」CTA

SEC-EDIT-3 介紹影片區

• 互動：最多 3 個 URL 輸入（0–3 彈性，按「+ 新增連結」）；每個輸入框失焦時即時驗證 URL pattern
  • YouTube：youtube.com/watch?v= / youtu.be/
  • Vimeo：vimeo.com/{id}
• 錯誤：URL 格式錯誤或非白名單時，輸入框紅框 + 提示「目前僅支援 YouTube 與 Vimeo」
• 儲存：URL 解析後存 {url, provider, video_id}

SEC-EDIT-4 欄位顯示偏好區

• 元件：4 個 checkbox（資本額 / 設立日期 / 負責人 / 董監事）
• 預設（D15）：資本額未勾選（對外隱藏）；設立日期、負責人、董監事已勾選（對外顯示）
• 無開關（D15）：聯絡電話、公司地址、員工人數——延續既有 WPort，恆常公開，mockup 不得出現隱藏 checkbox
• 副標：「以下欄位可控制是否於公開頁顯示；電話、地址、員工人數恆常公開。」

SEC-EDIT-5/6/7 痛點 / 得獎 / 里程碑

• 元件：可摺疊區塊，內含「新增」按鈕
• 項目卡：每項可拖曳排序（得獎/里程碑依年份預設排序）
• 儲存：批次儲存於公司編輯頁「儲存」按鈕觸發

SEC-EDIT-8 預覽（以求職者視角）

• 入口：公司編輯頁標題列「預覽（以求職者視角）」按鈕。
• 行為：開啟與 SEC-PUB-* 公開頁同一渲染，套用 field_visibility——勾選「不顯示」的資本額 / 負責人 / 設立日期 / 董監事在預覽中不出現（電話、地址、員工恆常顯示，D15）
• 預覽橫幅：頂部顯示「預覽模式 — 這是求職者看到的公司頁；隱藏的欄位不會顯示」，並提供「結束預覽，回到編輯」。
• Why：企業設定可見性後最常見的疑問是「對外到底長怎樣」；提供 WYSIWYG 預覽降低誤設風險、提升敏感欄位開關的填寫信心。對標 LinkedIn /104 公司頁「預覽公開頁」。
• 與 pm_41 連結：公司 API 金鑰「公司資訊」scope（僅 Owner/Admin，pm_41 BR-API-CLI-006）讀寫的即本頁欄位與 field_visibility；CLI company view 對外輸出亦須同樣依 visibility 過濾（pm_41 §6.4）。

SEC-PUB-2 公司公開頁：統編顯示

• 顯示：統一編號：12345678（僅顯示號碼，不掛「經濟部已驗證」等徽章，D20）
• 信任訊號：求職者端以 BR-005 公司認證為準；上架職缺之公司皆須通過認證
• tax_id_verified：後端／鎖定用旗標，不對 C 端呈現徽章

7. 使用者動作與後端需求（User Actions & Backend Needs）

真正的 API path/method 由 backend-api-spec-generator 產出，此表僅標示「是否需要後端」。

8. API Hints（提示用，非最終 API 設計）

8.1 資料讀取需求（Read）

• HINT-GET-4：平台已支援市場清單

  • 對應區塊：SEC-REG-1b、SEC-EDIT-1
  • Path 範例：GET /v2/api/countries/supported
  • 輸出：[{ code, name, dial_code }]（v1：tw/vn/th）
  • 用途：註冊與編輯下拉選項；不回傳全球國家表

• HINT-GET-1：統編查詢（TW）

  • 對應區塊：SEC-REG-1, SEC-EDIT-1
  • 輸入：tax_id（8 碼）；前置：country_code = tw
  • 行為（D1）：① GCIS live（§12 endpoint，BE 代理＋≥24h cache）→ ② 查無則稅籍資料集本地查 → ③ 皆無回 found=false
  • 輸出：TaxIdLookupResult（含 raw_source）
  • 限流：單 IP/帳號每分鐘 ≤ 10 次

• HINT-GET-2：公司公開頁資料

  • 對應區塊：SEC-PUB-*
  • 輸入：enc_company_id
  • 輸出：Company 但需依 field_visibility 過濾 capital_amount / establishment_date / representative_name / directors（不過濾 phone / address / employee_count）
  • Gate：lifecycle_status != profile_complete 或 BR-014 未滿足 → 404（與搜尋顯示條件一致）

• HINT-GET-3：公司編輯頁資料（管理端）

  • 輸入：enc_company_id
  • 輸出：Company 全欄位（含敏感欄位、lifecycle_status、profile_complete）；權限：Owner / Admin

• HINT-GET-5：公司資料完成度（BR-014 checklist）

  • 輸入：enc_company_id
  • 輸出：{ profile_complete, missing_fields: string[], lifecycle_status }
  • 用途：註冊精靈完成度條、公司編輯頁、發布職缺前 gate

8.2 資料寫入需求（Write）

以下僅為「需要支援的寫入動作」，欄位命名與 path 由 OpenAPI Spec 決定。

• HINT-MUTATION-1a：建立公司 draft（Step 1）

  • 輸入：country_code + name + phone + tax_id（三國必填，§4.4.4） + derived overrides（選填）
  • 行為：建立 lifecycle_status=draft；BE 先驗證 tax_id 格式（VN/TH checksum；TW 8 碼 checksum）→ 非法回 422；僅 TW 接續 D1 瀑布重查 → 命中則 tax_id_verified=true 並鎖定
  • 不要求 logo_url

• HINT-POST-validate-tax-id（格式驗證；可獨立 endpoint 或併入 MUTATION-1a）

  • 輸入：country_code + tax_id
  • 輸出：{ valid: boolean, normalized?: string, error_code?: string }
  • 用途：FE blur 時可選呼叫；BE 寫入時必須重驗（不可僅信 FE）

• HINT-MUTATION-1b：更新公司（註冊後續步驟／編輯頁）

  • 輸入：可變欄位（含 logo_url、intro、產業等）
  • 行為：每次 PATCH 後 BE 重算 BR-014；全滿足 → lifecycle_status=profile_complete、profile_complete=true

• HINT-MUTATION-2：更新公司基本資料 + visibility

  • 輸入：可變欄位 + field_visibility（4 個 boolean）
  • 行為：合併更新；統編欄位若已鎖定則拒絕變更

• HINT-MUTATION-3：上傳 Banner

  • 輸入：image binary
  • 行為：回傳 banner_url；前端再呼叫 MUTATION-2 將 banner_url 寫入 Company

• HINT-MUTATION-4：批次取代痛點 / 得獎 / 里程碑 / QA / 影片

  • 輸入：陣列（含排序）
  • 行為：先驗證每項上限與字數 → 替換整段陣列

• HINT-MUTATION-5：重新拉取登記資料

  • 輸入：enc_company_id
  • 行為：D1 瀑布（GCIS → 稅籍）→ 更新 derived（保留 tax_id_locked）→ 失敗保留舊資料

9. 導航 / Storybook Map

• Storybook 標題：Mockups/Company/CompanyEditRegisterV2
• Stories 路徑：storybook/src/stories/mockups/company/CompanyEditRegisterV2.stories.ts
• 交付 story：僅 一個 互動預覽（Default）；禁止為各步驟另建書籤 story，一律用 Controls 切換
• Storybook 連結：https://storybook.wport.me/?path=/story/mockups-company-companyeditregisterv2—default
• 情境控制（Controls，僅流程切換）：
  • scenario：register-step-tax-id | register-step-logo | register-step-page | register-step-verify | register-done | public-profile
  • companyPageContext（僅 register-step-page）：register-wizard | backend-edit
  • registerCountry / taxIdApiBehavior（僅統編步）
• 畫面內互動（不提供 Controls）：Banner 上傳、介紹影片 URL、公開頁欄位顯示勾選等，直接在 mock UI 操作
• 求職者視角預覽（SEC-EDIT-8）：scenario=register-step-page + companyPageContext=backend-edit 時，編輯頁標題列「預覽（以求職者視角）」→ 切至 public-profile 並顯示預覽橫幅；亦可直接選 scenario=public-profile 檢視公開頁本身
• 對應 production 路由（僅供參考）：
  • 註冊：/company/register
  • 編輯：/company/{enc_id}/edit
  • 公開：/company/{enc_id}

10. Flowcharts（User / System / Navigation）

10.1 User Flow（使用者操作流程）

flowchart TD
    A[使用者進入註冊精靈] --> A1[選擇公司註冊國家/地區]
    A1 --> B[輸入統一編號 + 聯絡電話等]
    B --> C{checksum<br/>通過?}
    C -- 否 --> C1[紅框提示<br/>格式錯誤]
    C1 --> B
    C -- 是 --> D[① GCIS live 查詢]
    D --> E{GCIS 結果}
    E -- 命中 --> F[自動帶入 derived]
    E -- 查無/失敗 --> E2{② 稅籍資料集}
    E2 -- 命中 --> F
    E2 -- 皆無 --> G[允許手動填寫]
    F --> H[Step 1 下一步]
    G --> H
    H --> I[POST /companies<br/>lifecycle=draft]
    I --> J[上傳 Logo<br/>強提示可跳過]
    J --> K[填寫其餘公司欄位<br/>PATCH 更新]
    K --> L{BR-014<br/>全滿足?}
    L -- 否 --> K
    L -- 是 --> M[profile_complete=true<br/>可出現於公司搜尋]
    M --> N[跳轉公司管理頁]
    N --> O[補 Banner / 影片 / 四區塊]
    O --> P[上傳驗證文件 BR-005]
    P --> Q[職缺可上架]

10.2 System Flow（前端狀態與資料流）

sequenceDiagram
    participant U as User
    participant FE as Frontend
    participant BE as Backend (代理)
    participant GCIS as GCIS live API
    participant TAX as 稅籍資料集（本地）

    U->>FE: 輸入統編 12345678
    FE->>FE: checksum 驗證
    FE->>BE: GET /companies/tax-id/lookup?tax_id=12345678
    BE->>BE: 檢查 cache (24h TTL)
    alt cache hit
        BE-->>FE: 200 + 帶入欄位 + raw_source
    else cache miss
        BE->>GCIS: ① 查詢
        alt GCIS 命中
            GCIS-->>BE: 公司資料
            BE->>BE: 寫 cache (raw_source=gcis)
            BE-->>FE: 200 + 帶入欄位
        else GCIS 查無
            BE->>TAX: ② 稅籍資料集
            alt 稅籍命中
                TAX-->>BE: 公司資料
                BE->>BE: 寫 cache (raw_source=tax_registry)
                BE-->>FE: 200 + 帶入欄位
            else 雙源皆無
                BE-->>FE: 404 NOT_FOUND（可手動註冊）
            end
        else GCIS 失敗/逾時
            BE->>TAX: ② fallback 稅籍
            TAX-->>BE: 命中或空
            BE-->>FE: 200 / 404 / 503
        end
    end

    FE->>U: 顯示帶入欄位 / 錯誤提示
    U->>FE: Step 1 下一步
    FE->>BE: POST /companies (country + tax_id + phone + name + derived)
    BE->>BE: checksum + D1 瀑布重查
    BE-->>FE: 201 + company (lifecycle_status=draft)
    U->>FE: 上傳 Logo（可選）／填寫其餘欄位
    FE->>BE: POST /upload (logo) + PATCH /companies/{id}
    BE->>BE: 重算 BR-014 → profile_complete
    BE-->>FE: 200 + company

10.3 Navigation / Story Flow

flowchart LR
    A[註冊精靈<br/>Step 1: 基本資料<br/>POST draft] --> B[註冊精靈<br/>Step 2: Logo + 公司頁]
    B --> C[註冊精靈<br/>Step 3: 補齊 BR-014]
    C --> D[profile_complete<br/>可搜尋]
    D --> E[公司管理頁]
    E --> F[BR-005 驗證]
    F --> G[職缺可上架]

10.4 Edge Case Coverage

11. Mock Data Schema（Mock 資料結構）

• 資料來源：僅 mock，不呼叫真實 API（含商工登記 API 由 Storybook 內以 sleep + 預設 fixture 模擬）
• CRUD 行為：mock 內所有新增/修改/刪除僅存在元件狀態，重新整理後還原
• 情境切換：
  • scenario=register-step-tax-id：Step 2 公司基本資料（統編 / 國家 / 電話）
  • scenario=register-step-logo：Step 3 上傳公司 Logo（強提示，可跳過）
  • scenario=register-step-page：公司頁（Step3CompanyPage + v2 注入）；以 companyPageContext 切換註冊精靈或後台編輯外殼
  • scenario=register-step-verify：Step 5 公司審核（對齊 Step4CompanyVerify）
  • scenario=register-done：Step 6 完成
  • scenario=public-profile：顯示公開頁（Banner / 影片 / 統編 / 三個底部區塊）
• Mock Fixtures（建議）：
  • 已驗證公司：tax_id=89121689 → 「熱火數碼資訊股份有限公司」（經濟部公示資料見 §13.6.1）
  • API 失敗示例：tax_id=99999999 → 503 API_DOWN
  • 查無資料示例：tax_id=11111111 → 404 NOT_FOUND

12. 實作備註（Implementation Notes）

• 禁止事項：

  • ❌ 本文件不直接定義最終 API path/method/JSON schema，僅提供 Hints
  • ❌ 不直接修改 prd/business-rules.md；BR-024 / BR-025 建議由 PM 於 PRD 確認後另開 PR 更新
  • ❌ 統編 API 不直接從 FE 呼叫（CORS + rate-limit + cache 集中管理）

• 注意事項：

  • 欄位命名與 Storybook/TS interface 一致（Storybook mockup 完成後以其為 SoT）
  • 商工登記公示資料 API 為經濟部商業司公開資料（具體 endpoint 由 RD 確認；建議於 https://data.gcis.nat.gov.tw/ 開放資料平台尋找最新 endpoint）
  • 權限對齊 BR-016：公司編輯頁所有寫入動作需 Owner / Admin
  • 既有 logo 規則延續 BR-006：Logo 為 BR-014 / profile_complete 必要條件；draft 不進搜尋（D17/D22）
  • Lifecycle（D22）：Step 1 POST 建立 draft；C 端曝光看 profile_complete；職缺上架看 BR-005
  • 欄位顯示偏好與公司搜尋顯示條件 (BR-014) 為獨立邏輯：visibility 控制公開頁顯示，與搜尋曝光資格無關
  • 統編 checksum 演算法：TW 見 §4.4.4；VN vn.mst；TH th.moa（BE 須與 FE 同規則，參考 storybook/src/utils/company-tax-id.ts）
  • 統編唯一性（沿用既有，非 v2 新規）：註冊「檢查可用性」→ validate-uniform-number（僅擋已認證占用）；認證前可共存 → 公司認證通過時防重複統編 → company-approval-process-flowchart.md §統編驗證規則

• 🟢 TW 統編查詢 — 雙軌（D1，2026-06-29 定案）：

  • ① GCIS live（優先） — 已實測可行（2026-06-23）：
  • 公司基本資料：GET https://data.gcis.nat.gov.tw/od/data/api/5F64D864-61CB-4D0D-8AD9-492047CC1EA6?$format=json&$filter=Business_Accounting_NO eq <統編>；公開、無金鑰。實測台積電 22099131 → HTTP 200 / 160ms，回 Company_Name、Capital_Stock_Amount(資本額)、Paid_In_Capital_Amount(實收)、Responsible_Name(負責人)、Company_Location(地址)、Company_Setup_Date(設立日期)、Company_Status_Desc(現況)。
  • 董監事（另一支 API）：GET https://data.gcis.nat.gov.tw/od/data/api/4E5F7653-1B91-4DDC-99D5-468530FAE396?$format=json&$filter=Business_Accounting_NO eq <統編>；實測 HTTP 200 / 137ms，回 Person_Position_Name(職稱)、Person_Name／Juristic_Person_Name、Person_Shareholding(持股)。→ PRD §5 的 directors[] 要接這支（與基本資料分開查）。
  • ⚠️ 日期是民國格式：Company_Setup_Date=0760221（民國76年→1987-02-21），BE 須 ROC→西元轉換後再存。
  • ⚠️ 正式上線：應用一可直接打，但系統介接需填表報備＋IP 白名單（opendata.gcis@gmail.com）、有流量限制 → 維持 PRD 既定「BE 代理＋≥24h cache」。
  • 結論：GCIS 技術可行；正式上線走 BE 代理＋cache＋IP 白名單（§14 #4 已完成）
  • ② 稅籍資料集（fallback）：財政部全國營業稅籍登記資料集，離線/批次匯入本地庫；GCIS 查無或失敗時接續查詢；raw_source=tax_registry_dataset
  • ③ 雙源皆無：允許手動註冊，tax_id_verified=false

13. 一致性審計（Stage 5 / 6 產出）

13.1 Field Mapping Table（SoT：本 PRD §5）

13.2 Constants Table

13.3 Event Dictionary

13.4 Terminology Dictionary

13.5 版本凍結表

13.6 Storybook 區塊對照表（PRD ↔ Mockup）

對應 Story：storybook/src/stories/mockups/company/CompanyEditRegisterV2.stories.ts
最後更新：2026/06/22

register-step-page 欄位狀態（統編已驗證）

13.6.1 經濟部 GCIS 欄位對照（Mock Fixture：89121689）

注意：GCIS「營業項目」為政府登記項目清單；WPORT「產業類別」為平台搜尋分類（BR-014），兩者分開維護。

13.7 PRD 問題清單

若上述項目於開發前皆達成共識，無 blocking 阻擋。

13.8 PRD Gap 補丁（2026-06-23 盤點；2026-06-29 決策收斂）

站在「能否直接餵 spec generator」角度盤點的缺口與冗餘。🔴 = 不補會讓 RD 產 spec 時亂猜；🟡 = 一致性/狀態機缺角；🟢 = 建議交代。 決策以 §1.5 D9–D22 為準；下表保留盤點脈絡，已決項標 ✅。

A. 缺少的決策（會卡 spec）

B. 多餘 / 噪音（建議刪或標示，避免污染 SoT）

C. Storybook ↔ PRD 落差（線上版比對，2026-06-23）

對線上 mockups-company-companyeditregisterv2--default 的來源元件逐一比對。「對齊方向」= 該改 PRD、改 mockup、還是先決策。D4↔G3、D5↔G4、D6↔G1、D8↔G5 同源（補丁缺口在 mockup 已現形）；D1/D2/D3/D7 為 mockup 與 PRD 直接對不上的新項。 📷 D2／D4／D8 已於 2026-06-23 用 Playwright 對線上版實際截圖確認（非僅讀碼）：D2 logo 步畫面寫「JPG/PNG/GIF/WEBP，5 MB 以內」；D4 「照片以及youtube url」欄底下是純文字 URL 框＋「+ 新增連結」、無照片上傳；D8 痛點區只有 標題/描述/移除/新增，draggable=0、無任何拖曳元件。

詞彙表（白話對照）

補丁狀態：§1.5 D9–D22 已拍板。待 mockup 對齊：D15 移除電話/地址/員工開關、D2 Logo、D3 公司名、D5 國家 disabled、D8 拖曳 UI、D20 移除統編徽章、D22 Logo 步可跳過 + 完成度 checklist。

13.9 PRD 產品/UX 合理性審查（2026-06-23；2026-06-29 PM 裁決）

與 §13.8 不同視角：本節質疑 PRD 本身是否合理，與 mockup 一致性無關。 裁決結果已回寫 §1.5；本表保留審查意見 → PM 回應脈絡，並補 為何採納／拒絕 供日後覆盤。

🔴 站不住腳 / 該重想

🟡 可議 / 建議調整

14. 同步修正清單（Sync-Fix List）

15. 下一步（Next Steps）

1. 以本 PRD 為輸入跑 storybook-mockup-gen → 產出 CompanyEditRegisterV2.stories.ts + 對應 mockup 元件
2. sb-deployed 部署 Storybook → 取得實際 Story URL → 回填本 PRD §1 + Coda
3. RD 依本 PRD §5 / §7 / §8 產 OpenAPI Spec（含 POST /companies draft、PATCH /companies/{id}、GET .../profile-completeness；GCIS 整合方案於該階段落地）
4. PM 將 BR-024 / BR-025 / Lifecycle（§4.2）寫入 business-rules.md（獨立 PR）

文件結束