W101 Admin CLI（公司後台終端介面）PRD

PRD 代號：pm_54 延續：pm_41（wport CLI v2 企業線）、pm_47（wport CLI v3 個人線・OAuth device flow）、pm_48（MCP connector・BR-039 通道來源審計）、pm_37（Enterprise REST） 參考架構：hotfire-digital/wport-cli（@wport/cli 0.9.2）——本 PRD 沿用其分層、契約與安全慣例，但另發套件、另發 registry（ADR-003） 目標 repo：W101-AMS（後端，主要工作量）、W101-Admin-Web（GUI parity 對照基準＋新增 1 個 web 觸點）、新建 W101-Admin-CLI 產品原則（沿 pm_41／pm_47，本 PRD 縮限）：Agent-first、deny-list 制、限量取代禁令 —— 但 admin 線因權限最高，額外加上「通道不得擴權」硬約束（BR-API-CLI-019） 本 PRD 的核心事實：GUI parity 在此案做不到也不該做——前端 18 個路由模組中僅約 2/3 有真實後端端點，其餘為 mock-only（§3.4、§13.2）

1. 文件資訊

• 文件類型：CLI + OAuth + 後端 API 擴充需求規格書
• 適用對象：CLI 工程師、後端（AMS）、前端（Admin-Web，1 個 web 觸點）、DevOps、資安、產品、QA、內部營運
• 最後更新：2026/09/09
• 版本：1.2.0
• PRD 識別碼：pm_54
• 對應 Storybook：待產出（§9 W-1 裝置驗證頁；文字規格為現階段 SoT，見 §17 sync-fix #9）
• Storybook（local-prd）：N/A — 尚未產出，以本 PRD §9 為 SoT
• Storybook（online）：N/A
• 文件入口：doc/feature/pm_54/admin-cli-prd.md
• 建立日期：2026/08/25
• 套件名稱：@wport/admin-cli（私有 registry）／執行檔 wportadm（ADR-003）
• 代號對照：pm_41 = 企業線 CLI｜pm_47 = 個人線 CLI｜pm_48 = MCP｜本 PRD pm_54 = 後台 admin 線 CLI

檔頭的 版本 與 最後更新 等於 §1.1 修訂紀錄最後一列。

1.1 修訂紀錄

2. 開發進度與設計來源

開發進度

• CLI PR #：[TBD]（新建 repo W101-Admin-CLI）
• 後端 PR #（W101-AMS）：[TBD]（admin device flow AS + session 撤銷 + X-Source 收錄 + audit channel）
• 前端 PR #（W101-Admin-Web）：[TBD]（§9 W-1 裝置驗證頁 + 已授權 CLI session 清單）

事實基礎（實查證據台帳）

本表是本 PRD 的證據台帳（gen-prd Rule 33）。凡斷言「既有程式怎麼運作」的句子都必須在此有一列； 沒有列的斷言，該句自帶 （推論，未實查）。來源欄格式固定為 repo@<short-sha> path:line。

Repo 基準（Rule 34 前置檢查，2026/08/25 執行 git fetch）：

基準選擇說明：本機 W101-Admin-Web 停在 main（落後 origin/develop 130 commits）、W101-AMS 停在 prod（與 origin/dev 相差 155/24）。實查 git diff --stat 後確認該落差主要為 squash-merge vs merge-commit 的歷史差異，src/ 實際內容差異僅限 gallery 兩個 view 與 company 模組的 chat-rooms repository，皆不在本 PRD 斷言範圍內。所有行號一律以 git show origin/<branch>:<path> 取得，未取自本機工作樹。

斷言 → 證據：

設計稿

• Figma：N/A（唯一新畫面為 §9 W-1 裝置驗證頁，沿用 Admin-Web 既有 Naive UI 版型）

3. 功能摘要（Feature Summary）

3.1 功能概述

• 功能名稱：W101 Admin CLI（wportadm）
• 主要使用者角色：
  • 內部後台管理員（admin / super_admin）：以終端機執行審核、治理、稽核查詢等重複性後台工作
  • AI Agent（Claude／Cursor，代表已授權的管理員操作）：執行「查詢 → 判讀 → 逐筆處置 → 留下理由」的審核流水線
  • CI／排程（受限）：僅讀取類與明確授權的維運任務（如 scheduler status）
• 核心目標：
  1. 把後台重複性審核工作（公司文件審核、職缺下架、履歷停用、帳號狀態）從「一筆一筆點 GUI」變成可腳本化、可稽核、可被 Agent 驅動的命令
  2. 把金鑰治理（企業 API Key、合作夥伴 Key）的事故處理時間從分鐘級壓到秒級——rotate / revoke 一行指令
  3. 建立 wport 的 admin 線通道治理基礎：可撤銷的短期憑證、通道來源標記、逐筆稽核，補上目前 GUI session（7 天 JWT）做不到的三件事
  4. 沿用 pm_41／pm_47 的終端契約（exit code、--output json、--fields／--minimal），內部工程師與 Agent 零學習成本

實際驅動力（Eric 2026/09/09）

以下三項是本案的真實需求來源，不是推導出來的策略理由：

D-2 同時是資安改善：目前之所以「撈瀏覽器 token」這招可行，正是因為 admin JWT 效期長達 7 天（§2 台帳）。這條驅動力與 §19 問題 1 是同一件事的兩面 —— 一個講「不好用」，一個講「不安全」。

北極星：「同仁已經在 IDE 裡工作，就讓後台的事也能在 IDE 裡做完」

這是本案的核心命題，其餘情境都是它的具體形態。

公司同仁——不只 RD，行銷與客服組也是——一天多數時間待在 IDE。目前只要碰到後台的事， 就得中斷手上的工作：切到瀏覽器、登入、逐層點選、手動複製貼回來。這個切換成本本身不大， 但它發生得很頻繁，而且擋住了自動化——凡是只能用滑鼠完成的事，就無法被腳本或 Agent 接手。

CLI 要達成的不是「多一種操作方式」，而是讓後台從「要切出去做的系統」變成「工作流裡的一個命令」。 衡量標準很簡單：同仁完成一件後台工作，需不需要離開編輯器。

這個命題對 CLI 的四個硬需求（皆納 v1）：

1. 機器可讀輸出：--output json / --fields / --minimal，讓結果能直接進下一段腳本或交給 Agent
2. 可分頁批次讀取：不必為了取一份清單而逐頁點選
3. 寫入可稽核：--reason 必填並寫入 admin_operation_logs，通道可辨識（channel=admin_cli）
4. 認證不打斷工作流：一次 login，之後 token 自動 refresh，不需反覆登入或手動搬憑證

⚠️ 第 3 點目前做不到：AMS 稽核表雖有 metadata 可擴充，但全 src/ 無 X-Source 收錄，也沒有 channel 欄位語意。這是 v1 的 Blocking 後端工作（§17 sync-fix #3）。

三個代表情境（對應 §3.1 的 D-1～D-3）

S-3 是延伸而非主軸（v1.1.0 調整）：初版曾以審核自動化為北極星，但那是從「哪些工作可自動化」推導出來的， 不是同仁實際提出的需求。真正的需求是 D-1——人已經在 IDE 裡了。審核自動化是這個前提成立後自然長出來的用法之一， 不是目的本身。

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

關於「權限最高所以不該做 CLI」的反向論證：這個直覺是對的方向、錯的結論。真正的風險不是「多一個通道」，而是「通道無法治理」。現況 GUI 通道的憑證是 7 天全權限、不可撤銷、不分來源；本 PRD 交付的 admin CLI 通道反而是第一個具備短 TTL、可撤銷、可限流、可逐筆稽核的 admin 通道。若因噎廢食不做，GUI 的既有風險一樣留在原地（§12 ADR-001 Consequences）。

3.3 SaaS Benchmark（高權限管理型 CLI 的認證慣例，RD 可自行驗證）

結論：管理型高權限 CLI 已收斂到 device-code / 瀏覽器 OAuth ＋ 短 TTL ＋ 可逐一撤銷 session。唯一大量使用長期 key 的 AWS，是因為其上有 IAM 這一整套獨立治理層在兜底——wport 沒有等價物，因此不核發長期 admin key（ADR-001、BR-API-CLI-018）。此結論與 pm_47 個人線「不發個人 API 金鑰」的裁決同源。

3.4 範圍界定（三層：✅ v1 會做 ／ 🕐 v2 以後 ／ ☢️ 絕對不做）

✅ v1（必含）

A. 認證與 session 治理

1. wportadm login：admin OAuth device flow（開瀏覽器、MFA 在瀏覽器完成）
2. wportadm logout / whoami
3. wportadm sessions list / sessions revoke [--all-others]
4. token 自動 refresh（過期前緩衝換新），refresh token rotation

B. 審核與治理命令（對映 AMS 已實作端點）

5. companies：search／view／update／approve／reject／delete
6. jobs：search／deactivate（無 view，後端缺端點，見 §17 #6）
7. resumes：search／view／disable／enable
8. accounts：search／view／status
9. admins：list／create／update／delete／reset-password／mfa-disable（限 SUPER_ADMIN）
10. mfa：status／initialize／verify-setup／disable／rebind／devices list／devices remove（操作者本人）
11. keys（企業 API Key）：list／view／create／rename／rotate／quota／revoke／usage／audit-logs／companies search／companies members
12. partners（合作夥伴）：keys CRUD＋regenerate／services bind｜unbind｜batch／tags CRUD／companies＋tags
13. marketing：posts／tasks／utm 各自 list／create／update／delete
14. dashboard stats
15. scheduler status / scheduler run <taskName>

C. 通用契約

16. exit code 契約（沿用 0／2／3／4／5，新增 6 = 需重新認證，ADR-006）
17. --output table|json、--fields、--minimal、--api、--timeout、--no-color
18. --confirm（破壞性操作）、--reason（所有寫入必填，ADR-007）
19. wportadm doctor：解析後設定、連通性、schema 指紋、目前身分與權限
20. wportadm config set|get|path|reset

D. 後端配套（AMS，皆為 v1 Blocking）

21. admin device flow 授權伺服器（4 個端點，§8.1）
22. CLI session 清單與撤銷 API
23. X-Source 收錄 + 稽核 channel 語意（補 BR-039 落差）
24. 寫入端點支援 Idempotency-Key

E. 前端配套（Admin-Web）

25. W-1 裝置驗證頁 /cli/activate
26. 帳號設定內「已授權的 CLI session」清單（可撤銷）

🕐 v2 以後（明確不在 v1）

• 前端 mock-only 模組的 CLI 化：purchase（訂單／方案／點數）、platform（廣告／通知／推薦設定）、system（角色／選單／備份紀錄）、gallery、drive、messages（線上回報／聯繫我們）、history、developer（Loki） → 這些前端頁面存在，但 AMS 無對應 controller，屬 mock-only（§13.2 對照表）。CLI 化的前置是後端先補端點，不在本 PRD 範圍
• 互動式審核 wizard（無 flag 時引導）
• Shell auto-completion
• Standalone binary（免 Node runtime）
• CLI 自身 i18n（v1 全繁中 + 英文 flag 名）
• MCP server 化（admin 線接 pm_48 架構）

☢️ 核彈 Deny List（admin 線永久禁止，對齊 BR-040）

⚠️ N-4 的誠實範圍：這條約束的是「CLI 不得新增旁路」，不等於「admin 線一定過得了 MFA」。實查顯示 MFA 目前是每帳號可選——新建管理員 mfaEnabled: false，登入時該旗標為偽即直接發完整 token（§2 台帳）。因此 device flow 的瀏覽器授權步驟，遇到未啟用 MFA 的帳號一樣會直接放行。修這件事不在本 PRD 範圍（見 §19 問題 1）。

這四項是上限也救不了的類別，與 pm_41／pm_47 的核彈清單同一判準：不是「限量」能解決的，才進核彈清單；能限量的一律走 BR-API-CLI-021／022 的限量條款（memory：CLI 能力哲學＝deny-list 制 + 限量取代禁令）。

3.5 成功條件

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

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

4.2 新規則提案（沿 BR-API-CLI 系列續編，自 018 起）

編號說明：主序列 BR-04x 目前有搶號情形（pm_46 提案 BR-039~043、pm_52 提案 BR-042，而 business-rules.md canonical 僅到 BR-041）。為避免再撞號，本 PRD 一律使用 BR-API-CLI 系列，續 pm_47 的 017 之後編號。

• BR-API-CLI-018（建議新增）：Admin CLI 認證僅限 OAuth device flow；不核發任何長期 admin API key。access token TTL 1 小時；refresh token 30 天 sliding／90 天 absolute，且必須 rotation（每次換發、舊者失效）。偵測到已失效 refresh token 被重用時，撤銷該 token family 全部憑證並記 audit event。
• BR-API-CLI-019（建議新增・資安核心）：Admin CLI token 繼承該 admin 既有 role／permission，不得擴權。後端須以 channel=admin_cli 標記該通道，並得對此通道單獨套用 deny list 與流量上限；通道標記不得由 client 自行宣告為其他值（以 token 綁定為準，X-Source 僅供交叉比對，不作為授權依據）。
• BR-API-CLI-020（建議新增）：所有經 CLI 的寫入必須寫入 admin_operation_logs，metadata 須含 channel；破壞性與審核類操作必須帶 --reason（1~200 字，必填），理由寫入 remarks。缺 --reason 於 client 端即擋下（exit 2），不送出請求。
• BR-API-CLI-021（建議新增）：Admin CLI 破壞性操作一律單筆 + --confirm；不提供批次刪除、不提供萬用字元選取（對齊核彈 N-1）。非破壞性的批次讀取不受此限。
• BR-API-CLI-022（建議新增）：Admin CLI 不提供全站 PII 匯出；accounts／resumes 讀取一律逐筆或分頁，單次分頁上限對齊 GUI 既有上限（RD 依實作端點定值）。
• BR-API-CLI-023（建議新增）：Admin CLI 不得修改操作者自身的 role／permission／帳號狀態（防自我提權與自我鎖定）。後端須在 domain 層擋下（不僅 client 端），對 admins update|delete 指向自身時回 403。
• BR-API-CLI-024（建議新增）：Admin CLI session 可於後台 GUI 與 CLI 逐一撤銷；撤銷後殘存 ≤ 30 秒。每 admin active CLI session ≤ 5，超額時汰換最久未使用者並通知。

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

本節描述需要追蹤什麼資料、為什麼，不規定 JSON 欄位名、雜湊演算法或 DB schema（gen-prd Rule 31）——那些屬 OpenAPI Spec，由 RD 決定。

5.1 實體列表

5.2 實體資料需求說明

E-1 Admin CLI 授權請求 需追蹤：待授權的裝置識別、給人看的短代碼、發起時間與到期時間、輪詢節流間隔、目前狀態（待授權／已授權／已拒絕／已過期）、以及授權完成後綁定到哪位 admin。 生命週期：短（建議 ≤ 10 分鐘，RD 定值）；過期即不可用，且不可重複兌換。 安全需求：短代碼須為人類可念但不可預測；輪詢須有節流，避免暴力兌換。

E-2 Admin CLI Session 需追蹤：屬於哪位 admin、建立時間、最後使用時間、來源裝置描述（作業系統／CLI 版本／建立時 IP）、目前是否有效、撤銷時間與撤銷者。 為什麼要有：這是 BR-API-CLI-024 的治理單位，也是補上現況「7 天 JWT 無法單獨撤銷」缺口的核心（§2 證據台帳）。 不追蹤：不記錄 CLI 執行過的命令內容（那是稽核表 E-4 的責任，避免雙寫與資料重複）。

E-3 Admin Refresh Token Family 需追蹤：同一次登入衍生的 refresh token 鏈、目前有效的那一枚、是否偵測到已失效者被重用。 為什麼要有：rotation 若無 family 概念，token 被竊後無法判斷是「合法 client 換新」還是「攻擊者重用舊的」。

E-4 後台操作稽核記錄（既有，需擴充） 既有已具備：操作者、模組、動作類型、目標表、目標 ID 與名稱、變更欄位明細、metadata、備註、IP、UA、requestId（admin-operation-log.interface.ts:42,51,53）。 本 PRD 需要新增的語意：這筆操作來自哪個通道（GUI／admin CLI／未來 MCP）。實作上可放 metadata 或獨立欄位，由 RD 決定；PRD 只要求「可用單一條件過濾出所有 CLI 操作」。 另需確保：remarks 對 CLI 破壞性操作為必填（BR-API-CLI-020）。

E-5 CLI 本機憑證檔 需追蹤：access token 與其到期時刻、refresh token、目前登入者的顯示名稱與 email、session 建立時間、目前連線的後端環境（dev／staging／prod）。 安全需求：檔案權限收斂至 owner-only、atomic write（沿用 wport-cli@c49a610 credentials-store.ts:160,163 的既有模式）；不同環境分檔存放，避免誤用 dev 憑證打 prod（沿用同檔 :63-64 的 channel 分檔慣例）。 硬性禁止：任何流程不得 echo token 到終端、不得寫入 shell history、不得進 git。

6. CLI 命令面與資料需求（Command Surface & Data Needs）

6.1 命令樹（v1 目標）

wportadm
├─ login / logout / whoami                  # OAuth device flow（§6.3）
├─ sessions list | revoke [--all-others]    # CLI session 治理
├─ doctor                                   # 診斷：設定 / 連通性 / 身分 / 權限 / schema 指紋
├─ config set | get | path | reset
│
├─ companies                                # → company/v2
│   ├─ search   [--status --keyword --page --page-size]
│   ├─ view     <enc_id>
│   ├─ update   <enc_id> --file patch.json --reason "..."
│   ├─ approve  <enc_id> --reason "..."     # document-approval
│   ├─ reject   <enc_id> --reason "..."     # document-approval
│   └─ delete   <enc_id> --confirm --reason "..."
│
├─ jobs                                     # → job/v2
│   ├─ search   [--status --keyword --page --page-size]
│   └─ deactivate <enc_id> --confirm --reason "..."
│                                           # ⚠ 無 view：後端缺端點（§17 #6）
├─ resumes                                  # → resume/v2
│   ├─ search / view <enc_id>
│   ├─ disable  <enc_id> --confirm --reason "..."
│   └─ enable   <enc_id> --reason "..."
│
├─ accounts                                 # → account/v2（前台求職者會員）
│   ├─ search / view <enc_id>
│   └─ status   <enc_id> --set <state> --confirm --reason "..."
│
├─ admins                                   # → admin/users（限 SUPER_ADMIN）
│   ├─ list / create --file a.json / update <enc_id> --file p.json
│   ├─ delete <enc_id> --confirm --reason "..."
│   ├─ reset-password <enc_id> --reason "..."
│   └─ mfa-disable <enc_id> --confirm --reason "..."
│
├─ mfa                                      # → auth/mfa（操作者本人）
│   ├─ status / initialize / verify-setup / disable / rebind
│   └─ devices list | remove <device_id>
│
├─ keys                                     # → admin/enterprise-api-keys
│   ├─ list / view <enc_id> / create --file k.json
│   ├─ rename <enc_id> --name "..."
│   ├─ rotate <enc_id> --confirm --reason "..." [--reveal]
│   ├─ quota  <enc_id> --set <n> --reason "..."
│   ├─ revoke <enc_id> --confirm --reason "..."
│   ├─ usage  <enc_id> [--period YYYY-MM]
│   ├─ audit-logs <enc_id> [--page --page-size]
│   └─ companies search | members <enc_company_id>
│
├─ partners                                 # → admin/partner-keys
│   ├─ keys list | view | create | update | regenerate | delete
│   ├─ services list | bind | unbind | batch | update
│   ├─ tags list | search | view | create | update | delete
│   └─ companies list | tags get | tags set
│
├─ marketing                                # → marketing/*
│   ├─ posts list | create | update | delete
│   ├─ tasks list | create | update | delete
│   └─ utm   list | create | update | delete
│
├─ dashboard stats [--from --to]            # → siteadmin/v2/dashboard/stats
└─ scheduler status | run <taskName> --confirm --reason "..."

6.2 全域契約

6.3 認證命令

# 首次登入：開瀏覽器完成授權（含 MFA），CLI 端輪詢取 token
wportadm login
#   → 顯示短代碼與驗證網址；SSH 環境加 --no-browser 只印網址

wportadm whoami                 # 顯示身分、role、權限摘要、session 建立時間（離線）
wportadm sessions list          # 列出此帳號所有 CLI session
wportadm sessions revoke <id>   # 撤銷指定 session
wportadm sessions revoke --all-others   # 保留當前，踢掉其餘（筆電遺失情境）
wportadm logout                 # 撤銷當前 session（server 端）+ 清除本機憑證

設計要點：MFA 一律在瀏覽器完成，CLI 端不收 TOTP 碼（核彈 N-4）。token 於過期前自動 refresh，使用者無感；refresh 失敗（撤銷／過期）時以 exit 6 明示需重跑 login，讓腳本能區分「重登即可」與「真的無權限（exit 3）」。

6.4 審核類命令（情境 S-3）

# 拉待審清單（Agent 讀 JSON）
wportadm companies search --status pending --output json --minimal

# 逐家取詳情
wportadm companies view <enc_id> --output json

# 判定並留下理由（--reason 必填，寫入稽核 remarks）
wportadm companies approve <enc_id> --reason "統編與登記文件相符，負責人一致"
wportadm companies reject  <enc_id> --reason "登記文件過期（2024/12 到期）"

# 職缺下架（破壞性 → 需 --confirm）
wportadm jobs deactivate <enc_id> --confirm --reason "違反 BR-009 職缺內容規範"

# 履歷停用 / 復用
wportadm resumes disable <enc_id> --confirm --reason "檢舉屬實：冒用他人經歷"
wportadm resumes enable  <enc_id> --reason "申訴成立，恢復"

6.5 金鑰治理命令（S4 主線）

wportadm keys list --output json
wportadm keys rotate <enc_id> --confirm --reason "疑似外洩，客戶回報" --reveal
wportadm keys revoke <enc_id> --confirm --reason "合約終止"
wportadm keys usage  <enc_id> --period 2026-08
wportadm keys audit-logs <enc_id> --page 1

--reveal 僅在 rotate／create 當下輸出一次完整新金鑰；其餘任何輸出一律遮罩至末四碼（沿用 wport-cli@c49a610 credentials-store.ts:73 的 maskKey 慣例）。

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

ACT-6 的三件事必須分開看：①端點路徑與 DTO 不改（CLI 打的是既有 /v2 端點）②X-Source 收錄與稽核 channel 是必做（BR-039 落差，v1 Blocking）③Idempotency-Key 是必做但可分批（僅破壞性與建立類端點需要，讀取類不需要）。

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

路徑一律含 global prefix /ams-api（W101-AMS@bf0fb57 src/main.ts:40）。以下為需求提示，最終契約由 RD 於 OpenAPI Spec 定案。

8.1 Admin Device Flow（新建）

RFC 8628 為對標基準（同 pm_47 個人線）。授權頁本身走 Admin-Web（§9），不在此列。

8.2 CLI Session 治理（新建）

8.3 既有端點（CLI 直接使用，路徑實查自 controller）

8.4 需注意的既有行為

• 全域 ValidationPipe 開 forbidNonWhitelisted（src/main.ts:79）：CLI 送出 body 時多帶一個欄位就會 400。--file 讀入的 JSON 必須先過本地 schema 驗證再送出，否則使用者會收到難以理解的 400。
• Swagger 僅非 production 掛載（src/main.ts:90）：CLI 的型別 codegen 只能從 dev／staging 取 spec，不能指望 prod 有 /ams-api/api-doc。此點與參考 CLI 的 gen:openapi:prod（從 prod swagger 取）做法相反，須改為從 dev 取或凍結 spec 進 repo（ADR-009）。
• 既有節流偏嚴：DEFAULT 為 5 次／60 秒（throttle.constants.ts:6-7）。CLI 的批次讀取情境（S-3 拉 30 家公司）會撞到 ADMIN_LIST 20 次／60 秒的上限，須為 CLI 通道評估獨立額度（§17 #8）。

9. Web 觸點（Admin-Web，文字規格）

三個觸點只有 W-1 是 v1。W-2／W-3 列 v2，理由見各節與 §14 —— 兩者在 v1 都有可用的替代路徑， 不擋出貨。這個取捨的完整推導記於 §19 問題 11，避免後人重新煩惱一次。

W-1 裝置驗證頁 /cli/activate（v1，Blocking）

• 進入方式：wportadm login 開啟瀏覽器導向此頁（或使用者手動開啟後貼上代碼）
• 未登入時：導向既有 admin 登入頁，完成帳密 + MFA 後回到本頁（沿用既有流程，W101-Admin-Web@0ee5ee9 CLAUDE.md:15）
• 頁面內容：
  1. 代碼輸入框（若網址已帶代碼則預填並唯讀）
  2. 顯示請求來源摘要：CLI 版本、作業系統、發起 IP、發起時間
  3. 明確文案：「授權後，這台裝置將能以你的身分（{role}）操作後台。你可以隨時在『帳號設定 → 已授權的 CLI』撤銷。」
  4. 兩個按鈕：授權 ／ 拒絕
• 結果狀態：授權成功、已拒絕、代碼過期、代碼無效 —— 四種各有明確文案與後續指引
• 安全要求：授權按鈕須防 CSRF；代碼比對失敗須節流，不得無限嘗試

W-2 CLI 存取頁（設定 > 帳號設定 新增分頁）（v2）

位置理由：src/views/setting/account/account.vue 已是分頁結構（BasicSetting / SafetySetting）， 而 SafetySetting.vue 正是管 MFA 的地方（mfa_enabled / mfa_secret / 綁定流程）。CLI 的 device flow 本來就要過 MFA，兩者相鄰在使用者心智上連得起來。且此頁每個 admin 都要能開 —— 這是它不能放在 會員管理 > 管理員列表 的原因（該區塊全部端點限 SUPER_ADMIN，見 §2 台帳）。

• 安裝：取得套件的方式 ＋ 可複製的指令
• 快速上手：login → whoami → 一兩個實際命令
• 我的已授權裝置：裝置描述、建立時間、最後使用時間、建立時 IP、是否為本次 session；可逐一撤銷、一鍵撤銷其餘
• 能力範圍說明：明講「後台部分頁面 CLI 沒有」（ADR-002 的後果）
• 與 CLI sessions list/revoke 讀寫同一組 API（§8.2），確保兩邊一致

為何列 v2：「我的裝置 ＋ 撤銷」CLI 自己就有 sessions list/revoke，不需要畫面；「安裝說明與憑證」 在 v1 的使用者規模（數名內部 admin）以人工交付即可。殘留風險低：人工發出的安裝憑證即使離職後未收回， 持有者也只是能下載一支 CLI —— 沒有有效 admin 帳號它什麼都做不了。套件存取權與後台存取權是不同信任域， 這一點在 v1 與 v2 都成立（連帶說明：安裝憑證不是 admin API key，不牴觸 ADR-001 與核彈 N-4）。

W-3 管理員列表的 CLI 治理視圖（會員管理 > 管理員列表）（v2）

位置理由：該頁本來就是「管理其他 admin」的地方（建帳號、重設密碼、關閉他人 MFA 皆在此）， 「撤銷他人 CLI session」屬同一類動作。

• 欄位：該管理員是否有活躍的 CLI session、最後使用時間
• 動作：super_admin 強制撤銷指定管理員的全部 CLI session
• 權限：沿用該頁既有的 SUPER_ADMIN 限制

為何列 v2：v1 有可用的緊急路徑 —— DELETE /ams-api/admin/users/{enc_id} 為軟刪除 （admin-user.service.ts:141），而 isActive() 要求 deletedAt IS NULL 且 status === ACTIVE （admin.repository.ts:193-199），此檢查在 jwt.strategy.ts:26 每個請求都會跑。因此刪除管理員後 其 CLI session 於下一個請求即失效。 已知限制：刪帳號是 all-or-nothing，無法「只收 CLI 但保留 GUI」。「筆電遺失但人仍在職」的情境， v1 只能刪帳號再重建 —— 這正是 W-3 的價值，但發生頻率不足以擋版。

10. Flowcharts

10.1 登入（Device Flow）

flowchart TD
    A[wportadm login] --> B[POST device/code]
    B --> C[顯示短代碼 + 驗證網址]
    C --> D{有瀏覽器?}
    D -->|是| E[自動開啟 /cli/activate]
    D -->|--no-browser| F[僅印出網址，使用者自行開啟]
    E --> G[Admin-Web /cli/activate]
    F --> G
    G --> H{已登入後台?}
    H -->|否| I[導既有 admin 登入頁]
    I --> J[帳密驗證]
    J --> K{已啟用 MFA?}
    K -->|是| L[TOTP 驗證]
    K -->|否| M[直接通過]
    L --> M
    M --> G
    H -->|是| N[顯示授權請求摘要]
    N --> O{使用者決定}
    O -->|授權| P[標記 request 已授權]
    O -->|拒絕| Q[標記已拒絕]
    B -.CLI 同時開始輪詢.-> R[POST device/token 輪詢]
    R --> S{狀態?}
    S -->|待授權| T[依 interval 等待後重試]
    T --> R
    S -->|已授權| U[取得 access + refresh token]
    S -->|已拒絕| V[exit 3：使用者拒絕授權]
    S -->|已過期| W[exit 3：代碼過期，請重跑 login]
    S -->|輪詢過快| T
    P --> S
    Q --> S
    U --> X[寫入本機憑證檔 owner-only]
    X --> Y[印出身分與 role，exit 0]

10.2 一般命令執行（含 token 生命週期與稽核）

sequenceDiagram
    participant U as 使用者/Agent
    participant C as wportadm
    participant S as 本機憑證檔
    participant A as AMS
    participant L as admin_operation_logs

    U->>C: wportadm companies approve <id> --reason "..."
    C->>C: 驗證參數（--reason 必填、破壞性需 --confirm）
    alt 參數不合法
        C-->>U: exit 2（不送出請求）
    end
    C->>S: 讀取 access token
    alt token 即將過期
        C->>A: POST token/refresh（rotation）
        alt refresh 失敗（已撤銷/過期）
            A-->>C: 401
            C-->>U: exit 6（需重跑 login）
        end
        A-->>C: 新 access + 新 refresh
        C->>S: atomic write 更新憑證
    end
    C->>A: PATCH company/v2/{id}/document-approval<br/>Bearer + X-Source: admin_cli + Idempotency-Key
    A->>A: JwtAuthGuard → RolesPermissionsGuard
    alt 權限不足
        A-->>C: 403
        C-->>U: exit 3（權限不足，非重登可解）
    end
    A->>A: domain 檢查（含自我提權防護）
    A->>L: 寫稽核（channel=admin_cli、remarks=reason）
    A-->>C: 200
    C->>C: 輸出淨化（ANSI/控制字元）
    C-->>U: table 或 json，exit 0

10.3 Edge Case 覆蓋矩陣

11. 實作備註（Implementation Notes）

11.1 CLI 必做

1. 沿用參考 repo 的 monorepo 分層（core 傳輸與型別／cli 命令層），但不共用套件（ADR-003）
2. exit code 契約集中一處定義，任何命令不得自行 process.exit 繞過
3. 所有終端輸出走淨化 helper（output.ts:43-44 同款）
4. 憑證 atomic write + owner-only + 依環境分檔
5. --file 輸入一律先過本地 schema 驗證再送出（§8.4）
6. token refresh 需處理併發：同一時刻多個命令不得各自 refresh 造成 rotation 互斥失敗

11.2 後端必做（AMS，v1 Blocking）

1. device flow 授權伺服器（§8.1）
2. CLI session 治理 API（§8.2）
3. X-Source 收錄 + 稽核 channel 語意（BR-039 落差）
4. 寫入端點支援 Idempotency-Key
5. 自我提權／自我鎖定的 domain 層防護（BR-API-CLI-023）
6. CLI 通道獨立節流額度評估（§8.4）

11.3 禁止事項

1. 不得為 CLI 開任何免 MFA 的憑證取得路徑（核彈 N-4）
2. 不得讓 client 自行宣告 channel 作為授權依據（BR-API-CLI-019）
3. 不得把 admin token 寫入 log、shell history 或錯誤訊息
4. 不得為了「方便」而放寬 forbidNonWhitelisted

11.4 相依性

12. ADR（架構決策紀錄）

ADR-001：Admin CLI 採 OAuth Device Flow，不沿用現有登入、不發長期 key

• Status：Accepted
• Context：AMS 現況登入發 7 天全權限 JWT、無 refresh、無法單獨撤銷單一 session（admin.service.ts:139）。CLI 若沿用，等於把最高權限憑證長期落地磁碟且不可治理。
• Decision：新建 admin device flow 授權伺服器；access token TTL 1h、refresh 30d sliding／90d absolute 且 rotation；MFA 一律在瀏覽器完成。不核發長期 admin API key。
• Consequences：後端工作量最大（新增 AS + session 治理）。換得可撤銷、可限流、可稽核的通道。既有 GUI 的 7 天 JWT 風險不在本 PRD 範圍內修復，列為 §19 問題 1。
• Decision maker：Eric｜Date：2026-08-25

ADR-002：v1 範圍＝AMS 已實作端點全包，明確放棄 GUI parity

• Status：Accepted
• Context：Admin-Web 有 18 個路由模組、34 個 api 檔，但 AMS 僅 12 組真端點；purchase／platform／system 等為 mock-only（§13.2）。pm_41／pm_47 的「GUI 能做什麼 CLI 就做什麼」在此無法成立。
• Decision：v1 覆蓋所有 AMS 已實作端點；mock-only 模組明列為 out of scope，其 CLI 化的前置是後端先補端點。
• Consequences：CLI 上線時「後台有些頁面 CLI 沒有」是預期行為，須在 README 與 doctor 明示，避免被當成缺陷回報。
• Decision maker：Eric｜Date：2026-08-25

ADR-003：獨立套件 + 私有 registry，不併入 @wport/cli

• Status：Accepted
• Context：@wport/cli 是公開 npm 套件，面向外部企業與求職者。admin CLI 握有後台最高權限，其命令面、端點結構、權限模型若公開發布等同送出攻擊地圖。
• Decision：另發 @wport/admin-cli（執行檔 wportadm）至私有 registry（GitHub Packages 或 npm private scope），僅內部 admin 可安裝。
• Consequences：需維護第二套 release 流程；兩套 CLI 的共用邏輯（輸出淨化、憑證儲存、exit code）會有一定程度重複。刻意接受此重複——跨 registry 共用套件會把私有實作細節洩進公開相依鏈。
• Decision maker：Eric｜Date：2026-08-25

ADR-004：通道不得擴權，token 繼承既有 role／permission

• Status：Accepted
• Context：admin CLI 若自帶權限模型，會出現「GUI 看不到但 CLI 做得到」的不一致，且無法沿用既有 RolesPermissionsGuard（roles-permissions.guard.ts:30-47）。
• Decision：CLI token 完全繼承該 admin 的 role 與 DB 權限；後端額外標記 channel=admin_cli，僅用於限縮（deny list、限流），不得用於放寬。
• Consequences：CLI 能力面自動隨既有權限模型演進，零額外維護。代價是無法為 CLI 設計「唯讀專用」的窄權限 token——列為 v2（§14）。
• Decision maker：Eric｜Date：2026-08-25

ADR-005：channel 以 token 綁定為準，X-Source 僅供交叉比對

• Status：Accepted
• Context：BR-039 要求記錄寫入來源。若單靠 client 送的 X-Source header，任何持有 token 者都能偽造來源，稽核即失效。
• Decision：通道身分由 token 本身承載（device flow 發出的 token 天然帶 admin_cli 屬性）；X-Source header 仍照送，但僅作為交叉比對與除錯訊號，不作為授權或稽核的權威來源。
• Consequences：稽核可信度提高。若兩者不一致，應記為異常事件供監控。
• Decision maker：Eric｜Date：2026-08-25

ADR-006：新增 exit code 6 = 需重新認證

• Status：Accepted
• Context：參考 CLI 的契約中，401（token 過期）與 403（權限不足）都落在 exit 3。對自動化腳本而言，前者「重登即可」、後者「重登也沒用」，混為一談會導致無窮重試迴圈。
• Decision：新增 exit 6 專指「憑證失效，需重跑 login」；403 維持 exit 3。
• Consequences：與 @wport/cli 的 exit code 契約產生一處差異，須在兩份 README 明確對照。判定為值得的差異——admin CLI 的自動化情境比公開 CLI 更依賴這個區分。
• Decision maker：Eric｜Date：2026-08-25

ADR-007：所有寫入必填 --reason，破壞性另需 --confirm

• Status：Accepted
• Context：稽核表已有 remarks 欄位（admin-operation-log.interface.ts:42 所屬 interface），但 GUI 未強制填寫，導致事後追查常常只看到「誰在何時改了什麼」，缺少「為什麼」。
• Decision：CLI 通道一律強制 --reason（1~200 字），寫入 remarks；破壞性操作另需 --confirm。缺漏於 client 端即擋（exit 2），不送出請求。
• Consequences：CLI 的稽核品質高於 GUI。這會凸顯 GUI 端未強制填理由的落差，建議後續對齊，列 §19 問題 2。
• Decision maker：Eric｜Date：2026-08-25

ADR-008：破壞性操作不提供批次

• Status：Accepted
• Context：pm_47 個人線採「限量取代禁令」（批次投遞 ≤20/次）。但 admin 線的破壞性操作（刪公司、刪管理員）沒有等價的「限量後仍可接受」的失誤成本。
• Decision：破壞性操作一律單筆 + --confirm；不提供 --file 批次、不提供萬用字元。非破壞性讀取不受限。
• Consequences：S-3 的 30 家審核需逐筆呼叫（Agent 自然會迴圈，非阻礙）。與 pm_47 的哲學差異須在文件說明：限量取代禁令適用於可回復的操作，不適用於不可回復的。
• Decision maker：Eric｜Date：2026-08-25

ADR-009：型別 codegen 來源改為 dev 環境或凍結 spec

• Status：Accepted
• Context：參考 CLI 的預設 codegen 從 prod swagger 取（gen:openapi:prod）。但 AMS 的 Swagger 僅在非 production 掛載（src/main.ts:90），prod 無 /ams-api/api-doc。
• Decision：codegen 來源改為 dev／staging 環境；並將取得的 spec 凍結進 repo 作為 fixture，使 CI 可離線重現且能 diff 出後端 DTO 變動。
• Consequences：與參考 CLI 的做法相反，須在 README 明確說明原因，避免後人「照抄 prod 版」而困惑。
• Decision maker：Eric｜Date：2026-08-25

ADR-010：不做 MCP，v1 只做 CLI

• Status：Accepted
• Context：pm_48 已建立 MCP connector 架構，理論上 admin 線可比照。
• Decision：v1 只交付 CLI。admin 線 MCP 化列 v2，且須先累積 CLI 通道的實際稽核與濫用資料。
• Consequences：Agent 需透過 CLI 而非原生 MCP tool 操作，體驗略遜但完全可用。換得「先在可控通道觀察一段時間」的安全緩衝。
• Decision maker：Eric｜Date：2026-08-25

ADR-011：不做 mock 模式

• Status：Accepted
• Context：Admin-Web 本地開發為純 Mock 模式（CLAUDE.md:47），CLI 是否比照？
• Decision：不做。CLI 一律打真實後端，環境以 --api 或環境變數切換，並依環境分檔存憑證。
• Consequences：CLI 的本地開發需要一個可用的 dev 後端。避免了「mock 與真實行為不一致」這類最難查的缺陷。
• Decision maker：Eric｜Date：2026-08-25

ADR-012：jobs 無 view 子命令，不為此擋版

• Status：Accepted
• Context：實查 job/v2 僅有 search 與 deactivate，無單筆詳情端點（job.controller.ts:14,23,57）。
• Decision：v1 的 jobs 命令群不提供 view；以 search 的結果欄位替代。後端補端點後再加，不因此擋 v1 出貨。
• Consequences：jobs deactivate 前無法在 CLI 內取得完整職缺內容供判讀，Agent 需依賴 search 回傳欄位。列入 §17 sync-fix #6 追蹤。
• Decision maker：Eric｜Date：2026-08-25

ADR-013：CLI session 上限 5，超額汰換最久未使用

• Status：Accepted
• Context：無上限則憑證累積無法治理；上限過低則多機工作（筆電／桌機／CI）受阻。
• Decision：每 admin active CLI session ≤ 5，超額時汰換最久未使用者並於下次登入告知。
• Consequences：正常使用不受影響。異常累積會自然浮現。數值屬營運參數，調整不需改版 PRD。
• Decision maker：Eric｜Date：2026-08-25

ADR-014：不追蹤 CLI 執行過的命令內容

• Status：Accepted
• Context：session 實體是否要記錄「這個 session 跑過哪些命令」？
• Decision：不記錄。命令的後果已由既有 admin_operation_logs 逐筆承接（含變更欄位與理由）；session 只治理憑證生命週期。
• Consequences：避免雙寫與資料重複。代價是「純讀取類命令」不留稽核痕跡——判定可接受，與 GUI 瀏覽行為不留稽核一致。
• Decision maker：Eric｜Date：2026-08-25

13. 四大一致性表格

13.1 欄位對照表

13.2 GUI 模組 vs 後端端點對照（本 PRD 的範圍界定依據）

「AMS controller 無」＝該前端模組目前由 mock/ 提供資料，無真實後端端點（W101-Admin-Web@0ee5ee9 mock/README.md:25）。

13.3 常數表

13.4 事件字典

13.5 術語字典

14. 版本凍結表

15. Token / API 契約完整性

16. Mock Data Schema

N/A —— 本 PRD 不產 Storybook mockup（§9 為文字規格）。CLI 本身不做 mock 模式（ADR-011）。

17. Sync-Fix List

18. Email Template

N/A —— 本 PRD 不觸發任何郵件。

唯一相近的情境是 session 汰換（ADR-013）與 refresh 重用偵測（§15）。兩者 v1 以後台事件記錄呈現，不寄信；若後續要加安全通知信，屬獨立需求。

19. PRD 問題清單

20. 下一步（Next Steps）

1. 本 PRD 交 gen-prd-checker 做對抗性審查（Backend RD／Security／SRE 三 persona）——admin 線是最高權限通道，這一關不可略過
2. RD 依 §8 產出 AMS 的 OpenAPI Spec（device flow + session API + 既有端點的 channel／冪等擴充）
3. 前端依 §9 產出 W-1／W-2；可先用 gen-storybook-mockup-gen 出 mockup
4. gen-trello-project-setup 建卡（1 goal + FE／BE 兩張 delivery，另需第三張給 CLI repo）
5. §4.2 的 BR 提案送審後寫入 business-rules.md
6. §19 問題 1（GUI 通道的 7 天 JWT）獨立立案——本 PRD 只負責不讓新通道重蹈覆轍，不負責修舊的

附錄 A：三條 CLI 產品線對照

關鍵差異的理由：前兩條線的使用者是客戶，設計目標是能力最大化（deny-list 制、限量取代禁令）。後台線的使用者是我們自己，設計目標是可治理——同樣的 deny-list 哲學，但判準從「會不會擋到使用者」換成「出事時查不查得出來、關不關得掉」。