企業後台網域切割（wport.me → business.wport.me）PRD

產出 persona：CEO with PM Background（＋ Research-Driven Technical PM 補技術裁決）。
目標 repo：W101-Web（apps/recruitment 為主，apps/main-site／packages/* 連帶）、W101-TalentSearchHub、W101-AMS、邊緣路由（Cloudflare／nginx）。
關聯：pm_51（複製公開網址）、pm_40（company_pay）、pm_37／pm_41／pm_48（Enterprise API／CLI／MCP）、pm_39（第三方登入）。

1. 文件資訊

• 文件類型：需求規格書（平台基礎建設；跨 repo；不產 Storybook）
• 適用對象：前端（main-site／recruitment／user）、後端（TSH／AMS）、DevOps、產品、QA、客服營運、行銷
• 最後更新：2026/08/20
• 版本：1.2.4
• PRD 識別碼：pm_52
• 對應 Storybook：N/A（無新畫面；見 ADR-010）
• Storybook（local-prd）：N/A — 以本 PRD 為 SoT
• Storybook（online）：N/A
• 文件入口：doc/feature/pm_52/business-domain-split-prd.md
• 建立日期：2026/08/18
• 現況網域：企業後台 https://wport.me/recruitment/*
• 目標網域：企業後台 https://business.wport.me/*（root path）

1.1 修訂紀錄

2. 開發進度與設計來源

開發進度

• 前端 PR #（W101-Web）：TBD
• 後端 PR #（W101-TalentSearchHub）：TBD
• 後端 PR #（W101-AMS）：TBD
• 邊緣路由 / DNS：TBD（Cloudflare 設定，非 repo 內）

設計來源（本 PRD 的事實基礎＝實查程式碼，非推測）

設計稿

• Figma：N/A（無新畫面；既有 Header／Footer／登入頁不改版）

3. 摘要

3.1 功能概述

• 功能名稱：企業後台網域切割（Business Domain Split）
• 主要使用者角色：企業使用者（Owner／Admin／Manager／Member）＝主要受影響者；求職者與訪客不應感受到任何變化
• 核心目標：
  1. 讓「公開內容」與「企業營運後台」在網域層級分家：wport.me = 對外品牌與 SEO 資產，business.wport.me = 企業工作台
  2. 讓兩者可獨立部署、獨立快取、獨立防護規則、獨立回滾，縮小每次上線的爆炸半徑
  3. 讓企業客戶有一個可以口頭傳達、可寫進採購文件、可加進公司防火牆白名單的專屬入口
  4. 為後續 admin.wport.me（內部）／business.wport.me（企業）／wport.me（公開）三層命名體系定調

3.2 為什麼現在做（策略理由）

關於「切換卡住」的誠實說明：網域切割本身不會修好這個問題 —— 它只是把問題推到必須面對的位置。真正修它的是本 PRD 的 session 工作：cookie 升為單一 SoT（ADR-004）、讀取順序反轉、切公司「先寫入再跳轉」的順序約束（§6.2 SEC-SWITCH）、以及 6 處直讀 localStorage 的修正（§13 sync-fix #2）。

換句話說：這條線遲早要收，切網域只是強迫我們一次做對。反過來說，若跳過這些工作直接切網域，business.wport.me 會有自己獨立的 localStorage，現況「偶爾卡住」會惡化成「幾乎每次切換都要重登」—— 所以 §13.2 才把這幾項全部標為 v1 Blocking。

3.3 SaaS Benchmark（公開可觀察之網域慣例，RD／PM 可自行驗證）

結論：招募／B2B SaaS 的主流是「公開站 apex ＋ 企業端獨立子網域，且子網域走 root path」。wport 選 business.* 而非 employers.*／hr.*，理由是 wport 的企業端不只招募（含 CRM、方案購買、API 金鑰、未來獵頭），business 語意涵蓋面最廣且中英文都好念。

3.4 範圍界定

v1（必含）

1. 新網域上線：business.wport.me 提供企業後台 SPA（root path），DNS／TLS／邊緣路由到位
2. 同源後端：business.wport.me 下同時代理 /api、/v2/api、/ams-api、/chat、/socket.io（ADR-006）
3. Session 跨站可用：登入狀態、選定公司（x-company-id-enc）在 wport.me 與 business.wport.me 之間一致（ADR-004）
4. 舊網址轉址：wport.me/recruitment/* → business.wport.me/*（先 302、觀察期後轉 301；ADR-005），保留 query
5. 相容轉址：business.wport.me/recruitment/* → business.wport.me/*（吃下漏改的舊絕對路徑）
6. 前端跨站連結修正：getUrl() 由 origin 拼接改為 app origin 解析；Header／Footer／UserDropdown／切換身分／登出等跨站入口全數改用解析結果（ADR-007）
7. 登入回跳：未登入進 business.wport.me → 導 wport.me/auth?redirect=...，登入後跳回原目標（ADR-003）
8. 通知 deep-link：scope=2（企業）解析到 business origin，維持「query 不放絕對 URL」的防護（ADR-007）
9. 後端連結改用新網域：TSH 邀請信／通知 redirect_path、AMS 審核通知改讀 BUSINESS_DOMAIN
10. SEO／爬蟲邊界：business.wport.me/robots.txt 回 Disallow: /＋X-Robots-Tag: noindex
11. 直接讀 localStorage.getItem('token') 的 6 處改走 getToken()（否則新網域首次進站必定判定未登入；見 §13 sync-fix #2）

Out of scope

• ❌ 求職者後台 /user 不搬（維持 wport.me/user/*；ADR-011）
• ❌ 公開頁（職缺、公司、活動、內容頁）不搬、URL 不變 —— pm_51 複製出來的網址仍是 wport.me
• ❌ admin.wport.me 不動
• ❌ 不做企業後台改版／不改任何後台功能行為
• ❌ 不做 Storybook（ADR-010）
• ❌ 不改 JWT 結構、不改權限模型、不改 currentUserType 判定機制
• ❌ 不導入 HttpOnly cookie ＋ refresh token 輪替（列 v2；ADR-012）
• ❌ 不換 email 寄件網域（SPF／DKIM／DMARC 完全不動）

3.5 成功條件

4. 商業規則對齊

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

4.2 新規則提案

BR-042（提案）：網域職責分界

• wport.me（含 www）：公開內容與求職者端。可被索引，是唯一對外分享的網域。
• business.wport.me：企業後台。一律 noindex＋Disallow: /，不得放置任何需要被搜尋引擎收錄的內容。
• admin.wport.me：內部後台，僅內部人員。
• 任何對外複製／分享的網址一律指向 wport.me（含 pm_51 複製公開網址、社群分享、QR code）。
• 新增任何 *.wport.me 子網域前，須評估其對 session cookie 的影響（見 ADR-012）。

建議於本 PRD 通過後回寫 business-rules.md（版本 → 1.11.0）。

4.3 衝突檢查

無硬衝突。

公開頁識別碼不受影響（明確聲明）：公司／職缺公開頁的 enc_id 由 DB id 加密而來，與網域無關；公開頁 https://wport.me/companies/{enc_id}、https://wport.me/job/{enc_id} 留在 apps/main-site（pages/companies/[id].vue、pages/job/[id].vue），URL 一字不改。既有分享連結、SEO 索引、pm_50 的 Admin 開公司頁動線皆不受本次切換影響。

註：同一個 enc_id 也被當作 x-company-id-enc（選定公司）使用 —— 值不變，但載體變了：它必須跟 token 一樣升級為 Domain=.wport.me 的共享 cookie，否則兩站選定公司會不一致 → 403（見 ADR-004、§10.4）。

職缺／公司：哪些留、哪些搬（RD 開工對照表）

切割線沿著系統既有的「公開頁 vs 後台管理頁」分界走，不是沿著資料實體走：

• 判準（＝ BR-042）：要被索引、要能對外分享的 → wport.me；要登入才看得到的 → business.wport.me
• 企業端的「預覽頁」屬於後台：/preview-job、/preview-company-info 視覺上長得像公開頁，但它是需登入的後台路由，跟著搬
• ⚠️ 同路徑不同 host 的組合：切換後會同時存在 wport.me/jobs（求職者搜尋）與 business.wport.me/jobs（職缺管理）。功能上無衝突，但這正是「後台連結必須明確帶 origin、不得用相對路徑或 location.origin」的直接理由（§13 sync-fix #3／#7）

唯一需要點名的語意衝突：pm_51「複製公開網址」若以 window.location.origin 拼接，切換後會複製出 https://business.wport.me/job/{enc_id}（死連結）。pm_51 PRD 已將公開 URL 定義為常數 https://wport.me/job/{enc_id}、https://wport.me/companies/{enc_id}，實作必須照常數走，不得用 origin 拼接（見 §13 sync-fix #7）。

5. 資料實體與設定契約

Rule 31：本節描述「需要被追蹤／設定的資訊與用途」，不鎖死最終 env 變數名或 JSON 結構；命名供跨 repo 對齊參考。

5.1 實體列表

5.2 語意定義（參考介面，非最終實作）

/** 各 app 對外 origin。由 build-time env 注入，禁止用 window.location.origin 推導 */
interface AppOriginMap {
  main: string;      // https://wport.me        （公開站／登入入口／求職者端）
  business: string;  // https://business.wport.me（企業後台）
  user: string;      // https://wport.me        （求職者後台，本次仍在 main 之下）
}

/** 跨站 session cookie 契約 */
interface SessionCookieContract {
  name: string;        // 'token' / 'x-company-id-enc'（可加環境前綴，見 ADR-008）
  domain: string;      // '.wport.me'  ← 本次新增，現況為 host-only
  path: '/';
  secure: true;        // 本次新增
  sameSite: 'Lax';     // 本次明確化（wport.me 與 business.wport.me 屬同 site，Lax 即可）
  httpOnly: false;     // v1 維持 false（前端需讀）；v2 目標改 true，見 ADR-012
  maxAgeDays: 7;       // 維持現況（亦符合 Safari ITP 對 JS 寫入 cookie 的 7 天上限）
}

5.3 網域對照表（常數）

5.4 轉址對照表（v1 必須覆蓋）

通用規則：https://wport.me/recruitment/(.*) → https://business.wport.me/$1，保留 query string（fragment 由瀏覽器自動保留）。

5.5 容量／限制

6. 畫面區塊與資料需求

本功能不新增畫面，只改變既有元件產生連結與判斷狀態的方式。

6.1 區塊列表

6.2 各區塊需求

SEC-NAV 共用 Header／Footer

• 現況問題：getUrl() 以 window.location.origin 拼接，在 business 站會產生 https://business.wport.me/media-section/（404）
• 要求：所有跨站連結改用 AppOriginMap 解析。呼叫端需標明目標 app，例如 getUrl('/media-section/', 'main')、getUrl('/jobs', 'business')
• 相容：未標明 app 時維持「同 origin 相對路徑」語意，避免一次改動全站
• 涵蓋清單：packages/utils/src/constants/HeaderNavLinks.ts、packages/web-components/src/layouts/header.js（含 /recruitment/、/recruitment/dashboard、/recruitment/purchase-plan）、footer.js（${this.hostName}/recruitment）、packages/common-components/src/components/W101Header/**、W101Footer/**

SEC-SWITCH 切換身分

• 現況：setSelectedCompany(encId) → refreshToken() → navigate('/recruitment/')
• 目標：導向 AppOriginMap.business + '/'；因為跨 origin，必須是 hard navigation（window.location.assign），不可用 router.push
• UI 要求：跨站跳轉期間顯示既有 loading／遮罩直到頁面卸載，避免使用者看到「按了沒反應」後重複點擊
• 順序約束：先確定新 JWT 與 x-company-id-enc 已寫入共享 cookie，再跳轉。否則新站讀到舊值 → 403（見 §10.4）

SEC-AUTH 登入回跳

• 未登入直接開 business.wport.me/jobs → 導 https://wport.me/auth?redirect=%2Fjobs&app=business
• 登入成功後 main-site 依 app 參數解析 origin 後 hard navigate
• 安全：redirect 參數維持只接受 / 開頭的相對路徑（現況防護不放寬）；跨站以獨立的 app 參數表達，且 app 只接受列舉值（main｜business｜user），任何非列舉值一律當 main（ADR-007）

SEC-DEEPLINK 通知 deep-link

• 後端 notification-links API 回傳 redirect_path＋identity_scope（已存在）

實際呼叫鏈（v1.2.0 依實查修正）——main-site 不消費 redirect_path，它只把值 encodeURIComponent 後包進 to 參數轉手（apps/main-site/app/pages/notification-links/index.vue:68-95），真正解析的是下游 app：

BE resolve → redirect_path
  → main-site 包成 /recruitment/deep-link?to=<redirect_path>&scope=2&…（硬跳）
  → apps/recruitment/src/views/deep-link/index.vue 解析 to

• 承接頁 /deep-link 的行為必須改（v1.1.0 誤寫「不變」）。該檔兩個分支對前綴的假設不一致：

  分支	行	現行程式	給無前綴的 /messages
  A：不用切公司	35-36	to.replace(/^\/(recruitment|user)/, '') 後 router.push	剛好能動
  B：需要切公司	20-27	finalUrl = to + '?enc_id='，經 packages/common-components/src/stores/modules/global.ts:29 做 location.href，未去前綴	❌ 跳到網站根目錄 → main-site catch-all pages/[...slug].vue:14-16 執行 router.replace('/') → 靜默導回首頁

• 要求：兩個分支統一為「先去 /recruitment 前綴 → 再由 app 自己補上正確的 base／origin」。 apps/user/src/views/deep-link/ 是同款寫法，一併處理。

• 效果：改完之後同一段程式對「帶前綴的舊值」與「不帶前綴的新值」都正確 → 前後端不需要同版上線（見 §8.3 修正）。

• ⚠️ redirect_path 可能是空字串：buildRedirectPath() 對 PUBLIC_TARGET_TYPES （目前只有 COMPANY＝公開公司頁）回傳 ''，未知 target type 回 '/'。這兩條與 identity_scope 無關， 目標實際在 main origin。若前端照「scope=2 → business origin」硬對應會導錯。 目前後端只發 CONVERSATION / APPLICATION，此路徑休眠但存在 → 見 §13.3 問題 #9。

• 既有的 token 水合與 switch-role 語意不變，改的只有路徑與 origin 的組法。

SEC-SESSION Session 橋接

• Cookie 升為 session 的 SoT；localStorage 降為同源快取（ADR-004）
• 進站時：先讀 cookie，再回填 localStorage（現有 getToken() 的 fallback 順序需反轉為 cookie 優先，否則兩站不同步時舊值會贏）
• visibilitychange／focus 時重讀 cookie；與記憶體中的 token 不一致 → 重新水合或登出
• 401 攔截 → signOut()（維持現況）

SEC-EDGE 邊緣路由

business.wport.me 需具備與現行 wport.me 相同的後端分流：

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

8. API／基礎建設 Hints（非最終設計）

8.1 前端設定（build-time）

⚠️ 聊天室不走 axios（v1.1.0 的 ADR-006 未涵蓋）。packages/common-components/src/stores/modules/chat.ts:322-334 讀 VITE_CHAT_API_ORIGIN，packages/chat-core/src/chat.ts:89 以 io(\${apiOrigin}${namespace}`) 連**完整網址**， 不是相對路徑。現況各環境皆已設（.env.staging.example:11,31＝https://staging.wport.me`、 .env.production.example:11,31＝https://wport.me），但 business 網域需要新增一份 build 設定， 漏設會 fallback 到硬編的舊網域。同款硬編 fallback 共三處 （common-components/.../chat.ts、chat-core 呼叫端、apps/main-site/app/stores/modules/chat.ts:119-120），建議一併清理。

8.2 後端設定

⚠️ 現行 TSH／AMS 皆以 getBaseUrl()／getTalentUrl() 字串相接產生連結。本次不要求重構，但必須新增獨立的企業側網域來源。

前綴的兩種情況要分開看（v1.2.2 釐清，原措辭「禁止把 /recruitment 前綴留在後端字串裡」與 §13.4 #5b 的「選配」互相矛盾）：

情況	規定
新寫的網址組裝（邀請信 acceptUrl、公司資料管理頁 URL、任何走 getBusinessUrl() 的地方）	硬規則：不得帶 /recruitment 前綴。 新網域是 root path，帶了就是死連結
既有的 redirect_path 常數（notification-link-token.service.ts:43）	選配 cleanup（#5b）。 前端 R1 的去前綴邏輯對新舊兩種值皆正確，且 ADR-002 第二條相容轉址會接住；不做的唯一代價是後端字串殘留前綴

8.3 Read／Write 契約

• 無新 API endpoint。所有既有 API 的路徑、payload、錯誤碼一律不變。
• 唯一契約變更：通知 API 回傳的 redirect_path 語意由「main-site 可直接使用的絕對路徑」改為「目標 app 內的相對路徑」。此為語意變更（欄位名與型別皆不變，值的意思變了）。

v1.2.0 修正——不需要同版上線。 v1.1.0 此處寫「前後端必須同版上線」，與 §13.0 P3、§10.4 （皆稱 BE 可晚於 FE、相容轉址會接住）互相矛盾。正確的是後者。落地形狀：

R1 未上線前不得執行 R2（否則 SEC-DEEPLINK 表中的分支 B 會靜默失敗）。R1 上線後 R2 可隨時做， 甚至不做也不會壞（舊值由 ADR-002 的相容轉址接住），故 R2 屬 cleanup 而非阻塞項。

請求欄位與回應欄位的方向相反：請求欄位因 forbidNonWhitelisted: true 必須 BE 先接受； 回應欄位的消費者是 FE，寬容層要放在 FE。

新增回應欄位（v1.2.0，依 §13.3 問題 #9 決議）：通知 resolve 回應的 target 物件新增一個 顯式的目標 origin 欄位，讓前端不必從 identity_scope 推導要拼哪個網域。

8.4 Auth／合約最小集

9. 導航／交付 Map

• Storybook：N/A
• dev 驗收：https://developers.wport.me ＋ https://developers-business.wport.me（內網，192.168.50.143）
• Production：https://wport.me ＋ https://business.wport.me
• 驗收方式：dev 全流程手測（§10.4 全表）＋ main-site Playwright smoke ＋ recruitment 既有 unit／Cypress
• ⚠️ dev 驗不到的一項：邊緣轉址規則。prod 走 Cloudflare、dev 走內網 nginx，是兩套設定。轉址仍為 prod 首次上路，靠 ADR-005 的「先 302、關規則即秒回滾」管理風險（見 §13.3 問題 #7）

10. Flowcharts

10.1 User Flow — 企業使用者主動線

flowchart TD
    A["使用者開啟 wport.me"] --> B{已登入?}
    B -- 否 --> C["wport.me/auth 登入"]
    C --> D["寫入共享 cookie<br/>Domain=.wport.me"]
    B -- 是 --> D
    D --> E{有企業身分?}
    E -- 否 --> F[留在 wport.me 求職者動線]
    E -- 是 --> G[選定公司 setSelectedCompany]
    G --> H[switchRole 取得新 JWT<br/>寫入共享 cookie]
    H --> I["hard navigate 至<br/>business.wport.me/"]
    I --> J[business 讀 cookie 水合 session]
    J --> K{cookie 有效?}
    K -- 是 --> L["進入 /jobs 企業後台"]
    K -- 否 --> M["導回 wport.me/auth<br/>帶 redirect + app=business"]
    M --> C

    N["開啟舊書籤<br/>wport.me/recruitment/jobs"] --> O["邊緣 302/301"]
    O --> P["business.wport.me/jobs"]
    P --> J

10.2 System Flow — Session 跨站橋接

sequenceDiagram
    participant U as 使用者瀏覽器
    participant M as wport.me (Nuxt main-site)
    participant E as 邊緣 (Cloudflare/nginx)
    participant B as business.wport.me (recruitment SPA)
    participant API as TSH / AMS

    U->>M: 登入
    M->>API: POST 登入
    API-->>M: JWT
    M->>U: Set-Cookie token（Domain=.wport.me, Secure, SameSite=Lax）
    Note over M,U: 同時寫 localStorage（僅同源快取）

    U->>M: 選定公司
    M->>API: POST /switchRole (帶 x-company-id-enc)
    API-->>M: 新 JWT (currentUserType=2)
    M->>U: 更新共享 cookie（token + x-company-id-enc）
    M-->>U: location.assign(business origin)

    U->>E: GET business.wport.me/ （自動帶 .wport.me cookie）
    E-->>U: SPA index.html（no-store）
    U->>B: 啟動
    B->>B: getToken(): cookie 優先 → 回填 localStorage
    B->>API: GET /v2/api/... （同源，帶 Bearer）
    API-->>B: 200

    Note over U,B: 登出時：以相同 Domain 刪除 cookie<br/>兩站下次請求皆 401 → signOut()

10.3 Navigation — 網域職責

flowchart LR
    subgraph Public["wport.me（公開・可索引）"]
        Home["首頁／職缺／公司頁"]
        Auth["/auth 登入（唯一入口）"]
        UserApp["/user/* 求職者後台"]
    end
    subgraph Business["business.wport.me（企業・noindex）"]
        Jobs["/jobs 職缺管理"]
        Msg["/messages"]
        Acc["/account-center"]
    end
    subgraph Admin["admin.wport.me（內部）"]
        AdminApp[Site Admin]
    end

    Auth -->|"登入後・hard nav"| Jobs
    Jobs -->|"複製公開網址 pm_51（常數）"| Home
    Jobs -->|"切回求職者模式"| UserApp
    Public -.->|"301 /recruitment/*"| Business
    AdminApp -->|"開公司公開頁 pm_50"| Home

10.4 Edge Case Coverage

11. Mock Data Schema

• 無 Storybook：不需要 mock schema。
• 測試資料要求：dev 需至少一組「同時具備求職者＋企業身分、且隸屬 2 間以上公司」的帳號，用於驗證切換公司的跨站一致性。

12. ADR（架構決策紀錄）

ADR-001: 企業後台使用獨立子網域 business.wport.me

• Status: Accepted
• Context: 企業後台目前掛在公開站的 /recruitment 路徑下，與 SEO 資產、快取策略、防護規則混在同一個 URL 空間；企業客戶也難以口頭傳達入口。可選：(a) 維持路徑；(b) 獨立子網域；(c) 獨立 apex（如 wport-business.com）。
• Decision: 採 (b) 獨立子網域 business.wport.me。
• Consequences:
  • ✅ 與 admin.wport.me 形成一致命名體系；Cloudflare Origin 憑證 SAN 已含 *.wport.me，不需新憑證
  • ✅ 與 wport.me 屬同 site，cookie 可共享 → SSO 成本最低；SameSite=Lax 即可運作
  • ⚠️ 同 site 也代表沒有真正的信任邊界：*.wport.me 任一子網域的 XSS 都可讀到 session cookie（見 ADR-012）
• Alternative rejected: (c) 獨立 apex —— 會變成跨 site，cookie 無法共享，必須自建 SSO 交接（一次性 ticket）＋ SameSite=None，成本高出一個量級，且對 7 人團隊不成比例。(a) 維持路徑 —— 無法達成部署／防護解耦，且不符合 §3.3 業界慣例。
• Decision maker: Eric | Date: 2026-08-18

ADR-002: 新網域採 root path，/recruitment 前綴只保留為相容轉址

• Status: Accepted
• Context: 兩種做法：(a) business.wport.me/recruitment/*（只換 host，改動最小）；(b) business.wport.me/*（同時去掉前綴）。實查後發現 recruitment 的路由表本身已是 root-relative（NavLink 全部是 /dashboard、/jobs…），/recruitment 只由 Vite base 注入；app 內硬寫 /recruitment 的地方僅 9 處（多為 public 圖檔路徑）。
• Decision: 採 (b)。同時建立兩條相容轉址：wport.me/recruitment/* → business.wport.me/*，以及 business.wport.me/recruitment/* → business.wport.me/*。
• Consequences:
  • ✅ business.wport.me/jobs 語意乾淨，符合業界慣例
  • ✅ 第二條相容轉址讓「後端還沒改完 env」也不會壞 → 前後端可分批上線，不必同一秒切換
  • ⚠️ 需同步處理 public 靜態資產路徑（/recruitment/icon/...）與 Vite base
• Alternative rejected: (a) —— business.wport.me/recruitment/jobs 語意重複，且等於把技術債搬家；既然路由表本來就 root-relative，這次不做以後成本只會更高。
• Decision maker: Eric | Date: 2026-08-18

ADR-003: 登入入口集中於 wport.me/auth，business 站不複製登入頁

• Status: Accepted
• Context: 登入／註冊／第三方登入（pm_39，含 Apple Service ID 的 redirect_uri = https://wport.me）全部實作在 main-site（Nuxt）。若 business 站要自帶登入，等於在 Vite SPA 複製一套 auth，並新增 OAuth redirect URI 與 Apple Service ID 設定。
• Decision: business 站不做登入頁。未登入 → 導 wport.me/auth?redirect=…&app=business，登入後跳回。
• Consequences:
  • ✅ 第三方登入設定（Google／Apple）完全不需異動
  • ✅ 只有一份 auth 實作要維護；BR-001 等規則不會分岔
  • ⚠️ 企業使用者「輸入 business 網址 → 被彈回 wport.me 登入 → 再跳回」會有一次跨站往返，需靠 loading 與文案讓過程可理解
• Alternative rejected: business 自建登入頁 —— 為了省一次跳轉，換來兩套 auth、兩組 OAuth 設定與長期分岔風險。
• Decision maker: Eric | Date: 2026-08-18

ADR-004: Session 以 Domain=.wport.me 共享 cookie；cookie 升為 SoT，localStorage 降為快取

• Status: Accepted
• Context: 實查現況：browserSessionStorage 與 nuxtSessionStorage 都同時寫 localStorage 與 cookie，但 cookie 未設 Domain（host-only），且讀取順序是 localStorage 優先、cookie fallback。localStorage 是 per-origin，business.wport.me 會是全新的空間 → 不處理則跨站必定要求重新登入。
• Decision:
  1. token 與 x-company-id-enc 的 cookie 一律加 Domain=.wport.me; Path=/; Secure; SameSite=Lax
  2. 讀取順序反轉為 cookie 優先，localStorage 僅作同源快取
  3. 刪除 cookie 時必須帶相同的 Domain，否則刪不掉 → 另一站殘留殭屍 session
  4. 升級時一次性清掉舊的 host-only 同名 cookie（見 §13.0）
• Consequences:
  • ✅ 跨站 SSO 免後端改動、免新 API
  • ⚠️ 同名 cookie 若 host-only 與 domain 版本並存，document.cookie 讀取順序不確定 → 必須一次性清理
  • ⚠️ cookie 會被送往所有 *.wport.me（含 api／dev-api／staging／developers／admin）→ 見 ADR-008、ADR-012
• Alternative rejected: 一次性 handoff ticket 交接（各站 host-only cookie）—— 安全性較佳但需後端新增簽發／兌換 API、跨站登出要另做，成本不成比例；列為 v2 與 ADR-012 綁定評估。
• Decision maker: Eric | Date: 2026-08-18

ADR-005: 舊網址先 302 觀察 14 天，再轉 301

• Status: Accepted
• Context: 301 會被瀏覽器永久快取。若上線後發現重大問題想回滾，已經吃過 301 的使用者瀏覽器仍會自行跳到新網域，等同無法回滾。
• Decision: 切換首 14 天使用 302（暫時轉址）；穩定後改 301（永久轉址）並長期保留。
• Consequences:
  • ✅ 觀察期內關掉邊緣規則即可秒級回滾（達成 S4）
  • ⚠️ 302 期間 SEO 不傳遞權重 —— 本案不影響，因 /recruitment 本就 Disallow＋非索引資產
  • ⚠️ 需要一張明確的「轉 301」工單，否則會一直停在 302
• Decision maker: Eric | Date: 2026-08-18

ADR-006: API 與 WebSocket 走同源反向代理，不採 CORS 跨源

• Status: Accepted
• Context: recruitment 的 axios baseURL 實際為 undefined（VITE_API_BASE_URL 未設定），所有請求都是相對路徑，且 withCredentials: true。若讓 business 站跨源打 wport.me API，需要：改所有請求的 base、TSH CORS_ORIGIN／WS_CORS_ORIGIN 加白、每個非簡單請求多一次 preflight、且 credentials: true 下不得使用萬用字元來源。
• Decision: 在 business.wport.me 下複製現行的後端分流（/api、/v2/api、/ams-api、/chat、/socket.io），維持同源。
• Consequences:
  • ✅ 走 axios 的 API 層零改動；無 preflight 額外延遲；無 CORS 設定漂移風險
  • ⚠️ 例外：聊天室不走 axios（v1.2.0 補）。它讀 VITE_CHAT_API_ORIGIN 連完整網址， 所以「同源」不是自動達成的，而是要靠新網域的 build 把該值設成 https://business.wport.me。 漏設會 fallback 到硬編的舊網域 → 聊天室連不上。詳見 §8.1
  • ✅ 設定正確時 WebSocket 同源，WS_CORS_ORIGIN 追加僅為保險（已實查佐證：staging.wport.me 不在 prod 清單內卻正常運作）
  • ⚠️ 邊緣設定要維護兩份（wport.me 與 business.wport.me）→ 要求以同一份 template 產生，避免漂移
  • 🛟 仍建議把 https://business.wport.me 加進 CORS_ORIGIN／WS_CORS_ORIGIN 作為保險，成本近乎零
• Alternative rejected: 跨源 ＋ CORS —— 改動面更大、延遲更差、且把安全設定分散到環境變數裡。
• Decision maker: Eric | Date: 2026-08-18

ADR-007: 跨站跳轉一律「相對路徑 ＋ app 代號」，query 內禁止絕對 URL

• Status: Accepted
• Context: apps/main-site/app/utils/auth-redirect.ts 目前明確拒絕絕對 URL 與 protocol-relative //，這是既有的 open-redirect 防護。跨站之後，redirect 目標確實需要落在另一個 origin，最直覺的做法是「允許絕對 URL 但比對白名單」。
• Decision: 不放寬 redirect 參數的限制（仍只接受 / 開頭相對路徑）。跨站目標以獨立的 app 列舉參數表達（main｜business｜user），由前端在最後一刻用 AppOriginMap 解析成 origin；非列舉值一律 fallback 到 main。通知 deep-link 沿用既有的 scope 參數，語意相同。
• Consequences:
  • ✅ open-redirect 防護維持「預設拒絕」，不需維護 URL 白名單比對邏輯（正規化、大小寫、port、尾綴等常見繞過點全部不存在）
  • ✅ 新增網域時只要擴充 AppOriginMap，不必改防護邏輯
  • ⚠️ 呼叫端需同時傳 path 與 app，既有呼叫點要逐一檢視
• Alternative rejected: 允許絕對 URL ＋ origin 白名單 —— 白名單比對是 open-redirect 最常見的破口來源，收益只有「少傳一個參數」。
• Decision maker: Eric | Date: 2026-08-18

ADR-008: Session cookie 名稱加環境前綴，隔離 prod／非 prod

• Status: Accepted
• Context: cookie 一旦設為 Domain=.wport.me，就會同時送到 staging.wport.me、developers.wport.me、developers-business.wport.me、dev-api.wport.me、api.wport.me、admin.wport.me。實查 DNS：staging.wport.me、admin.wport.me（CloudFront）與 api／dev-api.wport.me（Cloudflare）皆公開可達；developers.wport.me 為內網。prod token 被送進非 prod 環境（或反之）會造成難以察覺的狀態污染——該站讀到另一個環境的 session，兩邊資料庫與使用者 id 不同，症狀難以追查。 本案讓這件事變得更相關：v1.2.0 新增的 developers-business.wport.me 同樣在 .wport.me 底下，dev 與 prod 會互相污染。
• Decision: cookie 名稱由環境變數提供前綴（例如 prod token／dev dev_token／staging stg_token），三個前端 app 與 main-site SSR 一致。prod 維持現名以免既有 session 全數失效。
• Consequences:
  • ✅ 環境間 session 不再互相污染
  • ⚠️ 讀寫 cookie 的地方必須全部走 SessionStorage 介面（現況已有此規範，但有 6 處違規直讀 —— 正好一併修）
  • ⚠️ dev／staging 使用者需重新登入一次（可接受）

v1.2.0 補述（依 §13.3 問題 #11 決議）：

• 殘留風險：prod 維持原名 token，所以忘了替新環境設前綴時，該環境會靜默讀到 prod 的 session—— 失敗方向是最差的那邊（不會報錯，只會某天有人發現「dev 站怎麼讀到正式站資料」）。
• 對策（已決議）：把「新增任何 *.wport.me 環境時必須設定 cookie 名稱前綴」列為部署檢查項， 不靠人記得。未採「每個環境都加前綴（含 prod）」的 fail-closed 版本，因為代價是正式站使用者全部登出一次。
• 這是治標，不是治本。根本原因是「所有環境共用 wport.me 這個註冊網域」，治本有二： ①非 prod 改用另一個註冊網域；②不共用 cookie，改一次性交接票（ADR-004 已評估為「成本高一個量級」）。 兩者皆列 v2，與 ADR-012 一起評估。
• ⚠️ 釐清一個常見誤解：ADR-012 的 v2 目標（HttpOnly ＋ refresh token）解不了本問題。 HttpOnly 擋的是「XSS 讀得到 token」，不是「cookie 送到別的環境」。加了 HttpOnly， Domain=.wport.me 的 cookie 照樣送到所有 *.wport.me。兩件事要分開處理。
• Decision maker: Eric | Date: 2026-08-18

ADR-009: 跨站狀態同步採「cookie 為準 ＋ 可見性重讀 ＋ 401 攔截」，不做即時廣播

• Status: Accepted
• Context: 現行跨分頁同步靠 storage event（AUTH-SESSION.md §7.7），但 storage event 與 BroadcastChannel 都是 same-origin，切站後 wport.me 與 business.wport.me 之間完全收不到彼此的廣播。
• Decision: 不追求即時。採三層：(1) cookie 為 SoT；(2) visibilitychange／focus 時重讀 cookie，與記憶體狀態不一致則重新水合或登出／reload；(3) 既有 401 攔截 → signOut()。同 origin 內的 storage event 行為維持不變。
• Consequences:
  • ✅ 零後端成本，覆蓋「另一站登出／切公司」的實際使用情境（使用者切回分頁時必然觸發 visibilitychange）
  • ⚠️ 使用者若把兩站分頁並排放著不切換，最長會延遲到下一次 API 呼叫才發現失效 —— 明確接受
• Alternative rejected: 後端 session 版本號輪詢 —— 為低頻情境增加持續性請求量，不划算。
• Decision maker: Eric | Date: 2026-08-18

ADR-010: 不做 Storybook

• Status: Accepted
• Context: 本次無新畫面，改動集中在路由、設定、連結產生方式。
• Decision: 不產 Storybook；以本 PRD ＋ dev 驗收為準。
• Consequences: §1 Storybook 欄位標 N/A；驗收改以 §10.4 edge case 清單逐條手測。
• Decision maker: Eric | Date: 2026-08-18

ADR-011: 求職者後台 /user 本次不搬

• Status: Accepted
• Context: apps/user 同樣是掛在 wport.me/user/* 的 SPA，理論上可一併切到 my.wport.me 之類。但求職者端與公開站的動線高度交織（看職缺 → 投遞 → 我的應徵），拆開會增加跨站跳轉次數，反而傷 C 端轉換率。
• Decision: 本次只切企業後台。/user 維持現狀。
• Consequences:
  • ✅ 範圍可控，C 端零風險
  • ✅ 本次建立的 AppOriginMap／cookie 契約已預留 user 欄位，未來要切成本很低
  • ⚠️ 短期內網域體系不對稱（企業有專屬網域、求職者沒有）—— 可接受，因為兩者的商業角色本就不同
• Decision maker: Eric | Date: 2026-08-18

ADR-012: 接受 .wport.me cookie 共享的爆炸半徑，並立下子網域守則；HttpOnly ＋ refresh token 列 v2

• Status: Accepted（附條件）
• Context: session cookie 目前不是 HttpOnly（前端需讀取），改為 Domain=.wport.me 後，*.wport.me 上任一應用的 XSS 都能讀到 token —— 這是真實的安全退化，不能因為「同 site 所以沒差」而略過。實查 DNS 現況：n8n.wport.me、developers.wport.me、storybook.wport.me、dev-admin.wport.me 解析到內網 IP（192.168.50.143，非公開可達）；公開可達的是 www／media／api／dev-api／admin／staging。
• Decision:
  1. v1 接受共享 cookie，因為目前公開可達的子網域全部是自家可控資產
  2. 立守則（併入 BR-042）：任何第三方或低信任應用（含 n8n、外掛、實驗性服務）不得掛在 *.wport.me 的公開可達位置；若必須，須先移到獨立 apex 或加 Cloudflare Access
  3. dev／staging 以 cookie 名稱前綴隔離（ADR-008）
  4. v2 目標：token 改 HttpOnly ＋ 短效 access token ＋ refresh 輪替，屆時 ADR-004 的共享 cookie 可退場
• Consequences:
  • ⚠️ 明確記錄「這是用安全換交付速度」，不假裝沒有代價
  • ✅ 守則讓風險可管理而非放任
  • 📌 v2 若採一次性 handoff ticket，可同時解掉 ADR-004 的共享 cookie 與本 ADR 的爆炸半徑
• Decision maker: Eric | Date: 2026-08-18

13. 實作備註

13.0 Migration ／ 相容 ／ Rollback（Rule 23 必填）

既有使用者的 session 遷移

M1 為冪等操作，重複執行無副作用；三個 app 都要做（誰先被開啟誰先遷移）。

分階段上線

關鍵：P3 之所以可以晚於 P2，是因為 ADR-002 的第二條相容轉址（business.wport.me/recruitment/* → /*）會接住後端還沒改的舊路徑。這是刻意設計的安全網，不是冗餘。

Rollback 決策點

• P2 出問題 → 關閉邊緣轉址規則 ＋ 前端 origin 設定改回 main（一次部署）
• P3 出問題 → 後端 env 改回（郵件連結退回舊網址，仍可用）
• P4 之後 → 已吃 301 的瀏覽器無法回滾，故 P4 需獨立核准

13.1 禁止事項

• ❌ 用 window.location.origin 產生任何跨 app 的連結
• ❌ 在 redirect query 放絕對 URL（ADR-007）
• ❌ 為了跨站把 cookie 設成 SameSite=None —— 兩者屬同 site，不需要，且是安全退化
• ❌ 直讀 localStorage.getItem('token')（一律走 SessionStorage 介面）
• ❌ 讓 business.wport.me 的 index.html 進 CDN 快取
• ❌ 在新寫的後端網址組裝裡帶 /recruitment 前綴（新網域是 root path，帶了即死連結）
  • ⚠️ 這條不涵蓋既有的 redirect_path 常數——那一處是選配 cleanup（§13.4 #5b），不是禁止事項。兩者的差別見 §8.2 的對照表
• ❌ 在 business.wport.me 放任何需要被索引的內容
• ❌ 直接上 301（必須先 302 觀察）

13.2 一致性表（Stage 5／6）

Field mapping

Constants

Event dictionary

GA4 說明：wport.me 與 business.wport.me 同屬一個註冊網域，GA4 預設 cookie 網域為最高層級註冊網域，工作階段不會斷，不需要設定跨網域評估；但仍建議把 business.wport.me 加入「不需要的參照連結網址」清單以防自我參照。此段請行銷／RD 於 GA4 後台實查確認後再定案。

Terminology

Version freeze

13.3 PRD 問題清單

13.4 Sync-fix list

14. 下一步

1. RD／DevOps 先回答 §13.3 問題 #1（prod 邊緣路由現況）—— 這是唯一會擋住排程的技術前提
2. FE 開 P0（cookie 契約 ＋ AppOriginMap ＋ 6 處直讀修正），可立即開工、與 P1 平行
3. DevOps 建 developers-business.wport.me（內網 DNS ＋ nginx vhost）走完 P1，用 §10.4 全表在 dev 驗收
4. 業務／客服準備企業客戶通知稿與教育訓練文件更新（新網址）
5. P2 切換 → 觀察 14 天（盯 auth.session_bridge_failed 與邊緣 404）→ P3 → P4 轉 301
6. 上線後回寫 business-rules.md BR-042

文件結束