License 控管機制 — 設計定稿

狀態：設計定稿｜建立日期：2026-08-08｜討論稿：discussion.html（v2，含市場調查與完整推理過程）

Guidant AI 即將以兩種模式對外銷售：雲端 SaaS（公司自營多租戶環境，授權後台指派、即改即生效）與落地部署 Host 版（整套系統進客戶機房，授權必須以不可竄改的憑證檔隨產品交付、可離線驗證）。兩種模式共用同一套 License 控管機制，核心需求：

1. 功能管控——root tenant 以外的所有租戶，可用功能均受 license 管控；未授權模組不出現在選單、API 拒絕存取。
2. 簽發能力——公司能產生 license 交付客戶，客戶開通後生效。
3. 有效期管理——支援起訖日與訂閱到期，到期後行為明確、漸進、可預期（提醒 → 寬限 → 唯讀），不直接鎖死。

端到端流程

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  A["① 簽約<br/>訂單成立<br/>（訂單編號·客戶代碼）"] --> B["② 簽發<br/>Web 後台選 Plan 產照＋序號<br/>寫入發照紀錄表"]
  B --> C["③ 交付<br/>Host：照＝合約隨貨<br/>SaaS：後台直接指派"]
  C --> D["④ 開通（Host）<br/>線上或離線<br/>綁定機器指紋"]
  D --> E["⑤ 使用<br/>模組守門·子租戶額度<br/>每日狀態檢查"]
  E --> F["⑥ 到期<br/>notice → grace → readonly<br/>（出廠預設終態＝永久唯讀）"]
  F --> G["⑦ 續約換發<br/>重簽整張新照替換<br/>舊照留歷史"]
  G --> E
  F -.->|"訂單未回簽<br/>但服務不可中斷"| H["臨時展延照<br/>type: extension<br/>只改到期日"]
  H --> E

整體架構

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  subgraph issuer["公司簽發端（獨立 repo·獨立 DB·內部部署，持有私鑰）"]
    WEB["極簡 Flask Web 後台<br/>客戶總覽頁＋簽發/換發表單<br/>Plan 套餐一鍵帶入"]
    CLI["簽章引擎＋CLI<br/>（Ed25519 私鑰簽章）"]
    LEDGER[("license_issuance 發照紀錄表<br/>＋plans 套餐表<br/>訂單編號／客戶代碼／序號／型態<br/>經銷商·抽佣欄位預留")]
    ACT["線上開通伺服器<br/>（掛雲端環境）"]
    WEB --> CLI
    CLI --> LEDGER
    ACT --> LEDGER
  end

  subgraph deliver["交付物"]
    LIC["license 檔<br/>（簽章 JSON）"]
    SN["開通序號<br/>（短碼，Host 版）"]
  end

  subgraph product["產品端（SaaS ／ Host 版共用）"]
    ADMIN["root tenant 系統管理後台<br/>上傳／驗章／指派／狀態總覽"]
    ENGINE["License 驗證引擎<br/>公鑰列表（kid 查表）編譯進後端"]
    STORE[("tenant_licenses<br/>現行照＋歷史照")]
    GUARD["授權守門<br/>common/authz 第六軸<br/>＋唯讀 gate＋選單/任務型態過濾"]
    CRON["每日排程<br/>到期狀態機檢查"]
    ADMIN --> ENGINE
    ENGINE --> STORE
    STORE --> GUARD
    CRON --> STORE
  end

  CLI --> LIC
  CLI --> SN
  LIC --> ADMIN
  SN -->|"線上開通（Host）"| ACT
  ACT -->|"自動下載照＋回傳機器指紋"| ADMIN

要點：私鑰只存在於左側——產品端只有公鑰列表與驗證邏輯，沒有任何簽發材料。SaaS 與 Host 版是同一個右側：SaaS 的「指派」在公司自營環境的 root tenant 後台完成（內部同樣走簽發產照），Host 版由客戶上傳照——驗證引擎、守門、狀態機完全共用。

十五項決策全數定案。標示「最終修正」者為 discussion v2 之後由決策者再拍板覆蓋的內容，以本表為準。

補充定案（原 discussion「待確認」清單的落點）：升級 Plan＝換發新照、立即生效——SaaS 後台改指派即生效；Host 版上傳新照當下生效，不重啟服務、機器未變不重跑開通。Plan 套餐組合與命名（Basic／Professional／Enterprise 草案）為簽發端 plans 表的 seed 起點，後台隨時可調。

本案掛進既有骨架，逐點盤點：

4.1 License 檔格式

License 檔為簽章 JSON，欄位分五組：

上表為照的內容欄位（簽章原文 payload 的組成）。落地成 .json 檔的信封格式見下方 v2 說明。

• tenant_id（tenant 綁定 欄）是簽發端的客戶識別代稱，產品端不對此欄位做強比對——照的實質綁定對象是 SaaS 版的 root 指派動作（後台把照寫入哪個租戶就綁哪個）或 Host 版的機器指紋（§4.7 開通時寫入開通紀錄供稽核），tenant_id 只是簽發紀錄與照內容用來對照客戶的標籤，不是產品端驗證邏輯的比對鍵。

檔案格式 v2：payload 打包（T-1.3，2026-08-08 起生效）

現行照檔（v1）是明文 JSON＋Ed25519 簽章——防竄改已足，但內文（模組清單、到期日、expiry_policy 等）客戶打開文字編輯器即可讀。決策者裁示：不讓客戶隨手看到內文。這不是加密——Host 版客戶持有整包程式碼，解碼邏輯終究可逆向，此設計本就不承諾密碼學保密；目的僅是「嚇阻一般翻閱」，故採壓縮＋編碼打包、不採對稱加密（金鑰反正藏不住，加密只多金鑰管理成本無真實安全增益）。

落地檔案信封改為：

{
  "format_version": 2,
  "kid": "<簽章金鑰識別碼>",
  "payload": "<zlib 壓縮＋base64 之 license JSON>",
  "signature": "<Ed25519 簽章>",
  "alg": "Ed25519"
}

• payload 是上表全部欄位（識別／時間／功能／綁定／完整性五組，kid 除外置於信封層）組成的 canonical JSON（key 排序、無多餘空白）先 zlib 壓縮、再 base64 編碼的字串。
• 簽章對象是 unwrap 後的 canonical bytes 原文，不是打包後的字串——驗章時先 base64 解碼＋zlib 解壓還原出原文，再用原文驗 Ed25519 簽章。這個順序保證：①換掉壓縮實作（如改用 gzip）不會讓既有簽好的照失效；②竄改 payload 任一 byte，解壓會失敗或還原出的 JSON 對不上簽章，兩者皆判定驗章失敗——防竄改能力與 v1 完全等價。
• v1／v2 並存：兩 repo（license_center 簽發端、compliance-manager-be 驗證端）的驗章引擎皆以有無 format_version 鍵區分版本，v1 明文舊照（無此鍵）沿用舊路徑直接對整個 dict 驗章，v2 信封先 unwrap 再驗。簽發端（CLI／Web）自 T-1.3 起一律只產出 v2；驗證端兩版皆收，理由是 FR-062 尚未正式出貨、DEV 環境已有 v1 測試照（T-2.3 手測用 lic-test-0001），拒收 v1 會讓既有驗收資料失效且無實際安全收益（v1/v2 差異只在「是否好讀」，簽章防竄改保證兩版一致）。待 v2 全面出貨後續一輪視需要再收緊為只收 v2，非本階段範圍。

檔案外皮 v3：.license ＋ PEM 風格 armor（T-1.5，2026-08-08 起生效）

user 驗收回饋：裸 .json 交付不專業。對齊業界慣例（JetBrains .key／GitLab .gitlab-license／Keygen PEM 風格 license file）定案改用自有副檔名＋PEM 風格文字塊包裝：

-----BEGIN GUIDANT LICENSE-----
<v2 信封整包 JSON，base64 編碼，64 字元換行>
-----END GUIDANT LICENSE-----

• 純外皮層，非格式重簽：armor 包裹的是 v2 信封（format_version/kid/payload/signature/alg）整包 JSON 的 base64 編碼，內層信封結構與簽章邏輯完全不動——armor_license／dearmor_license 只是「json.dumps → base64 → 加頭尾包行」與其逆操作，不碰 payload 打包或簽章演算法。
• 兩 repo 各自獨立實作（license_center.crypto.engine 與 common.license.engine），維持既有「零依賴、僅透過簽好的照檔交互」原則，不新增套件依賴。
• 產出端：license_center CLI（issue／extend／reissue）與 Web 下載（/issuance/download/<license_id>）一律輸出 <license_id>.license（armor 內容）；CLI 未指定 --output 時預設檔名也改用 .license。
• 驗證端兩式皆收：compliance-manager-be 上傳解析（LicenseVerificationService.upload_license）與 license_center CLI verify 皆先偵測是否含 -----BEGIN GUIDANT LICENSE-----，是則 dearmor_license 還原成 dict 再走既有 v2/v1 驗章路徑；不含 BEGIN 行（裸 JSON）照舊直接解析——同一批既有測試照與手測資料不受影響。
• 容錯：dearmor_license 對常見文字污染（CRLF、行尾空白、email 轉寄插入的引用空行）逐行 strip 後再 join 解 base64，避免客戶轉寄/複製貼上破壞格式。
• FE：上傳元件 accept 屬性加 .license，判斷邏輯以副檔名為準（非標準副檔名瀏覽器 MIME type 判定不可靠）；FileReader.readAsText 流程不變，讀出文字後偵測 BEGIN 行——armor 內容原樣以字串送到 BE（不在前端解包），裸 JSON 則沿用既有 JSON.parse。

4.2 簽章與驗證

• Ed25519 離線簽章（Python cryptography 庫），格式設計參考 Keygen 公開做法。
• 公鑰列表編譯進後端程式：[{kid, pubkey}]，不放設定檔、不放 DB；照內帶 kid，驗章時按 kid 查表。
• 時鐘回撥防護：系統持續記錄「見過的最大時間戳」，偵測到時間倒退判定異常；issued_at 晚於當下系統時間即拒收。
• 竄改處置：驗章失敗＝整張照無效，系統進入鎖定（「無有效照」的鎖定，與到期管線可組態終態無關）；本地留證（事件時間＋檔案指紋），有網路則回報公司端點。
• 防線分層：簽章防竄改 → 公鑰編譯進執行檔防替換 → 時鐘回撥偵測 → 蓄意破解（patch 產品程式碼）靠合約與稽核約束，技術上留存竄改證據作舉證材料。破解管理員帳號也無法自行簽發——產品內沒有私鑰、沒有簽發程式碼，只有「收照櫃台」。

4.3 簽發站設計（獨立 repo）

形態：極簡 Flask 應用（與主產品同技術棧）、獨立 repo、獨立 DB、部署公司內部不對外。Web 是殼、CLI 是引擎，兩者共用同一簽章引擎模組；air-gapped 簽發、Web 掛掉時仍可純命令列操作。

兩頁：

獨立 DB schema 草案（兩張表起步）：

license_issuance 發照紀錄表——財務對帳與稽核的權威紀錄、客戶總覽頁資料源：

plans 套餐表——Plan 與模組分層是 DB 資料，後台可增改，非寫死：

seed 起點：Basic＝基礎包；Professional＝基礎包＋問卷包＋雲端整合包；Enterprise＝全模組。改 Plan 只影響之後發的照（照內存展開後清單，範本改動不回溯存量）。

4.4 產品端資料模型：tenant_licenses

4.5 狀態機與排程

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
stateDiagram-v2
    [*] --> valid: 照生效
    valid --> notice: 距到期 ≤ notify.days_before（預設 30）
    notice --> grace: 到期日過（grace 啟用）
    notice --> readonly: 到期日過（grace 停用時直接唯讀）
    grace --> readonly: 寬限天數用盡（預設 14）
    readonly --> locked: lockout 啟用且 readonly.days 用盡<br/>（出廠預設 lockout 停用，此轉換不會發生）

    notice --> valid: 換發新照
    grace --> valid: 換發新照
    readonly --> valid: 換發新照
    locked --> valid: 管理員上傳新照

    valid: valid — 正常服務
    notice: notice — 全功能＋到期提醒（橫幅／email 依照內旗標）
    grace: grace — 全功能＋醒目警告
    readonly: readonly — 可登入·可看·可下載匯出，擋全部寫入（預設為終態）
    locked: locked — 鎖登入，僅管理員可進上傳頁（預設停用，可組態）

各段開關語意：

• 狀態轉換由每日排程驅動（複用 core/scheduler.py APScheduler，比照 framework_parse_job_cleanup 寫法）；任何狀態換發新照即回 valid。
• locked（若啟用）不是死路：管理員永遠可進 License 上傳頁上傳新照，登入與上傳端點在唯讀與鎖定狀態均豁免（防死鎖）。

4.6 執法設計

4.7 開通流程（三路）

序號／機器碼開通僅 Host 版適用；SaaS 送照管道是產品 root 後台向 License Center 請照（FR-062.10：帶 API token 打 LC 內部簽發 API，回照驗章後直接寫入租戶，客戶零動作、即改即生效）——LC 與產品 root 後台是兩個獨立系統獨立 DB，中間僅透過此內部 API 交互，不共用資料庫也不互相直寫。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant C as 客戶（管理員）
    participant R as 產品 root 後台（BE，獨立 DB）
    participant P as 產品端（開通頁）
    participant S as 公司開通伺服器
    participant I as License Center（簽發引擎，獨立 repo／獨立 DB）

    rect rgb(226, 240, 241)
    Note over R,I: 路徑 0 — SaaS：root 後台向 LC 請照（客戶零動作）
    R->>R: admin 按「向 LC 請照」（選租戶／方案／天數）
    R->>I: 帶 API token 打 LC 內部簽發 API（/issue 或 /extend）
    I->>I: token 白名單驗證 → 呼叫 issue_license／extend_license 簽出照
    I-->>R: 回傳簽章後 license（armor）
    R->>R: 驗章 → 落地寫入該租戶（event_type=lc_issue／lc_extend，即改即生效）
    end

    Note over I: Host 版：簽約後簽發產出 license 檔＋開通序號
    I->>C: 交付開通序號（短碼）

    rect rgb(238, 242, 243)
    Note over C,S: 路徑 A — Host 線上開通
    C->>P: 首次登入，系統偵測無照 → 導向開通頁
    C->>P: 輸入開通序號
    P->>S: 序號＋本機機器指紋
    S->>I: 核對序號 → 簽出綁定該機的照
    S-->>P: 回傳 license 檔（自動下載安裝）
    P->>P: 驗章 → 生效
    S->>I: 回寫紀錄：已開通＋機器指紋＋時間
    end

    rect rgb(251, 252, 252)
    Note over C,I: 路徑 B — Host 離線開通（封閉網路）
    C->>P: 首次登入 → 開通頁顯示本機機器碼
    C->>I: 將序號＋機器碼交付公司（郵件等既有管道）
    I->>I: 簽出綁定該機器碼的照
    I->>C: 回寄 license 檔
    C->>P: 上傳 license 檔
    P->>P: 驗章＋核對機器指紋 → 生效
    Note over I: 人工回寫紀錄：已開通＋機器指紋＋時間
    end

兩路共用同一張照格式與同一套驗證引擎，差別只在交付方式。機器綁定在開通當下完成；日後續約換照機器不變即不必重跑開通。線上開通伺服器掛雲端環境（定案不變）；但「開發＋全流程驗證」與「公網部署」已拆開處理——線上開通伺服器端點已在 local 落地並全流程驗證通過（BE 代打 LC 側公開 API，序號存在／未用／未過期三查＋防濫用鎖定），公網曝露／TLS／網域／防火牆等純部署動作留待雲端環境就緒後補驗（T-5.2，見 §5）。

FR-062.10：SaaS 續約免手動搬檔（產品後台直接向 LC 請照）

背景：原設計圖 4「路徑 0」把 LC 與產品 root 後台畫成同一個 participant，讀起來像「產品後台按一下、後面自動去簽發引擎拿照」，但兩者是獨立系統獨立 DB——實際上 SaaS 續約／加購／展延時，admin 必須先在 LC 端簽發下載 .license 檔，再切回產品後台上傳，兩趟手動搬檔。本設計補上一條產品端直接打 LC 內部 API 的線，取代人工搬檔，圖 4 已同步修正。

認證：API token 白名單機制（不複用 Host 版 activation 的一次性序號，因為簽發 API 沒有對應憑證）：

• LC 端新增 api_tokens 白名單表：token_name（來源名稱，如 product-dev／product-prod）、environment、token_hash（不存明文）、is_active（撤銷用停用不刪列）
• 每個產品環境（DEV／STG／正式站）各發一把 token；LC 端發照紀錄 issuer 欄位寫 token_name，帳本上每張照看得出由哪個環境請發
• 產品端請求帶 token（header），LC 端驗證比對白名單後才呼叫簽發邏輯

三支 LC 內部 API（新 blueprint，比照既有 activation 無 session＋passphrase 環境變數自動解鎖 pattern，直接呼叫既有純函式 issue_license／extend_license，不另抽 service）：

• POST /issue：新簽（customer_code／order_no／issued_to／tenant_id／plan_code／days／deployment_mode…）
• POST /extend：展延（license_id + days）
• GET /plans：回傳 active plans 供產品端 UI 下拉選擇

產品端三支對應端點（license_admin_route.py 同組，掛 @require_platform_admin_route）：

• lc-issue：呼叫 LC /issue → 回照走既有落地漏斗（_verify_signed_license + _store_verified_license，第五個進入口，傳 event_type=lc_issue）
• lc-extend：呼叫 LC /extend → 落地 event_type=lc_extend
• lc/plans：取得可選方案清單

失敗路徑照抄既有 activate_license_online() pattern：打 LC → 逐狀態碼轉 error code → 連線失敗回專屬碼 → 回照仍走本地完整驗章＋落地（BE 是唯一信任邊界，不因來源是 LC 就跳過驗章）；手動上傳路徑完全不動，作為 LC 不可達時的天然 fallback。

決策：不做 trial 強制——曾考慮「非 production 環境只能簽 trial 照」的防呆規則，最終不採：主站管理員即決策者本人，LC 環境未來也會與產品環境分開部署，白名單機制的目的是管理便利與可追溯性（可撤銷、可查來源），不是防範內部誤用；未來若接入多個 SaaS 平台，同一白名單機制可統一控管各平台來源。

Host 版序號開通流程零接觸（DEPLOYMENT_MODE 為產品實例層級 config，本案只在 SaaS 實例的 root 後台加按鈕）。完整拆棒與待調查六項逐條結論見母案 Notion CM-1175。

4.8 補發與換綁

防複製政策：換綁人工受理（受理時確認舊機已停用，不提供自助換綁）；同一客戶頻繁換綁是警訊，簽發端總覽頁標記提示。

簽發站 Web 設計（驗收回饋補充）

• UI 框架：採 Tabler（MIT，Bootstrap 5 基礎）。靜態資產 pin 版下載後放入 static/vendor/，不依賴外部 CDN、不引入前端 build 鏈——與簽發站「極簡 Flask、獨立部署」定位一致。
• 簽發 passphrase 自動解鎖：私鑰解密優先讀 .env 的 LICENSE_CENTER_KEY_PASSPHRASE 環境變數，設定後簽發／展延／補發表單免手動輸入。表單 passphrase 欄位僅於未設環境變數時顯示（air-gapped 備援：私鑰與簽發站不同機、或刻意不落地環境變數的場景）；輸入的 passphrase 只在單次請求記憶體內用於解密，不落地、不存 session。
• 「顯示用明文、交付用信封」原則：簽發結果頁與總覽頁的畫面呈現皆為解包後的明文欄位（照型態、部署模式、模組集、到期日等），方便內部核對；但照下載一律走完整簽章信封（v3 armor 或 v2 JSON），畫面明文不等於下載內容，避免內部人員誤把顯示用文字當交付檔轉發客戶。
• 照下載：結果頁下載走 armor_license（.license armor 格式，§4.1 v3）；總覽頁重下載走 get_if_current 守門（僅現行有效紀錄可重下載，作廢舊照不提供），輸出完整 v2 信封原文（不重簽）。
• 總覽詳情頁＋操作 Menu（T-6.4，驗收回饋追加）：總覽頁每列客戶代碼／名稱可點入詳情頁（/licenses/<license_id>，重用簽發結果頁樣板），非現行照（已被展延／補發／換綁取代）也可查詢供稽核，但畫面顯示「已被取代」提示＋接替筆連結、不顯示下載鈕（下載守門規則不變）；列尾原本平鋪的動作按鈕（下載／展延／補發／換綁）收成單一 Tabler dropdown Menu，新增「查看詳情」項。

4.9 金鑰生命週期

• 保管：私鑰檔以 passphrase 加密，加密備份至少兩處（密碼管理器／保險庫＋離線媒介）；license_issuance 同步備份。私鑰遺失且無備份＝無法再簽發與續約——備份紀律是營運前提，不是建議。
• passphrase 保管方式：開發／內部部署階段得直接存放簽發站 .env 的 LICENSE_CENTER_KEY_PASSPHRASE（與私鑰檔同機），供 Web 自動解鎖（§4.8）；正式對外簽發仍須密碼管理器保管＋兩處站外加密備份，.env 存放僅限私鑰與簽發站同機、風險可控的內部場景，不可作為正式營運的唯一保管方式。
• 簽發機不綁定：私鑰是檔案，換機還原備份即恢復；照的驗證完全不看簽發機器。
• kid＋公鑰列表（初版就做）：只編譯一把公鑰的話，日後換鑰＝逼全部客戶同時升級，商業上不可行。
• 計畫性輪替（每 2–3 年）：產新 kid → 新版產品公鑰列表加入新鑰（保留舊鑰）→ 新照用新鑰簽 → 存量照到期換發自然轉新鑰 → 舊鑰無存量照後下一版移除。
• 私鑰洩漏（急件）：立即產新鑰；緊急出只帶新鑰的產品版本（＝吊銷舊鑰）；換發全部現行照並通知客戶升級——發照紀錄表就是換發清單。

4.10 SaaS 後台操作

root tenant 後台對 SaaS 租戶可執行：

顯示層 i18n（驗收回饋補充）：產品端照型態／部署模式／模組集顯示文字補齊 FE i18n（zh-tw／en 兩語系）；簽發端 LC 後台介面中文化。

root tenant 顯示修正（T-2.4，驗收回饋追加）：root tenant 開「我的授權狀態」頁原本顯示與一般租戶相同的「尚未授權」空狀態，語意錯誤——root tenant 是設計上無條件豁免 license 執法、永不發照的特權租戶，沒有照是「設計如此」不是「還沒買」。GET /license/status 補 is_root_tenant 旗標（沿用既有 platform-admin 軸判定），FE 依旗標顯示「本租戶為系統管理租戶，不受 License 授權管控」；此旗標同時供全域到期橫幅判斷是否對該租戶顯示。

依賴鏈：.1 → .2 → .3 → .4；.5 依賴 .1＋.2（與 .3/.4 可並行）；.6 依賴 .1；.7 依賴 .3（＋.2 的表）、migration 為上版前最後動作；.8 依賴 .4。

FR-062.1 簽發端地基（階段 1）— 依賴：無 · 對現有系統零侵入

FR-062.2 產品端驗照與狀態顯示（階段 2，只讀不執法）— 依賴：FR-062.1

FR-062.3 狀態機排程與橫幅（階段 3，仍不擋操作）— 依賴：FR-062.1＋.2

FR-062.4 執法進場（階段 4，帶環境開關可整體關閉）— 依賴：FR-062.1–.3

FR-062.5 開通流程（階段 5，兩張 case：離線先行）— 依賴：FR-062.1＋.2（可與 .3/.4 並行）

FR-062.6 簽發 Web 後台（階段 6）— 依賴：FR-062.1

FR-062.7 通知與既有租戶發照 migration（階段 7，migration 為上版前最後動作）— 依賴：FR-062.3

FR-062.8 角色權限矩陣 license 對齊（階段 8，驗收回饋追加）— 依賴：FR-062.4

FR-062.4 執法上線後，選單、任務型態選擇器、API 端點三處都已受 license 控管，但角色權限矩陣完全沒有 license 維度：只買基礎包的租戶，管理員在角色編輯頁仍看得到且勾得下去問卷／AI 儀表板／檢測工具的能力點，勾了會真的寫進 role_capabilities，但選單不顯示、API 照樣 403——形成「可以授予一個不存在的權限」的困惑（與 Jira 可把 unlicensed user 加進 project role 的知名困惑同型）。

業界對照（2026-08-10 調查）三種模式：A 反灰＋原因（Frontegg／Schematic 建議做法，Salesforce 為極致版——permission 勾不到時會明確報缺哪張 license）／B 整功能隱藏（GitLab custom roles 為 Ultimate 專屬）／C 讓你勾但無效（Jira，公認的困惑來源）。本案採 A。

既有可借鏡樣板：is_platform 已是同形狀的雙層縱深（ui_route_route.py UI 層過濾 ＋ DB trigger trg_role_capabilities_platform_guard）。license 軸照抄同一形狀，判定條件從「是不是平台能力點」換成「租戶買了沒」。

整體驗收：以只買基礎包的測試租戶驗——矩陣頁反灰＋原因可見、存量項標「已授予但未生效」、繞過 FE 直打 API 得 403、新開子租戶預設角色不含未授權模組、上傳含 survey 的新照後重整即可勾選（無需重啟或資料修復）、root 與總開關關閉時行為與現況完全一致。

統計：8 子需求 × 28 子任務（初版 17 ＋ 驗收回饋期追加 11：T-1.3／T-1.4／T-1.5／T-6.3／T-2.4／T-6.4，以及 FR-062.8 五支 T-8.1～T-8.5（角色矩陣 license 對齊，2026-08-10 驗收回饋），另 expiry_policy v2.1 格式升級併入 T-7.1 未另列）；BE 19、FE 8、簽發站新 repo 11（部分子任務跨 repo，重複計入）。

分層邊界依 BE 程式碼相依盤點（2026-08-08 唯讀分析）實證劃定：基礎包缺一系統不成立，加值包關掉系統仍完整。本節內容為簽發站 plans 表與模組分層的 seed 資料——上線後屬簽發端商務設定，後台可調，非產品端寫死。

基礎包（隨基本授權附，21 模組）

project、module-frame、compliance-framework、workflow、flow_template、audit、device、information-system、dashboard、report、project-summary-report、user、role、department、tenant、bulletin、bulletin-list、feedback、feedback-view、notify_config、storage-config

關鍵相依證據：開專案 hard 依賴 module-frame 三件組 clone（app/project/service/project_start_app_service.py:335-344）；flow engine 是任務執行骨幹（app/grc/service/prep_job_generation_service.py）；device／information-system 是 SSP 受評範圍支撐資料（app/grc/service/project_service.py:299-316）；dashboard SQL 串 6 模組資料（infra/grc/repository/grc_dashboard_repo_impl.py:185-201）。

加值包（4 包）

不販售

• 移除：resource（死模組）、cruise-project（舊架構殘留）。
• 平台級（僅 root 使用、不販售）：issue-integrate-config、ldap-config、smtp-config、log、system-menu、system_config。

既有 35 個 capability 粒度內的重組（把某模組換包、Plan 增減模組）零工程成本——只是簽發端資料異動；新增新粒度（例如把某模組再拆細）才需要產品端補守門。

以虛構客戶「宏遠科技」（HY-001）為素材，逐項可勾稽：

1. Host 版發照與離線開通：簽發後台選 Plan「Professional」產照（照內含展開模組集＋出廠預設 expiry_policy）＋序號、紀錄表新增一筆（含訂單編號／客戶代碼）→ 客戶首次登入被導向開通頁 → 抄機器碼交公司 → 簽綁定照回寄 → 上傳驗章通過全功能生效 → 紀錄表回寫「已開通＋指紋＋時間」。
2. 模組守門：Professional 租戶看不到 AI 儀表板選單、打 AI 儀表板 API 403；已授權模組全部正常；任務型態下拉含問卷（有問卷包）；另一 Basic 租戶下拉無問卷。
3. 到期全過程（出廠預設）：短效照驗證 到期前 30 天進 notice（橫幅＋email）→ 到期進 grace 14 天（醒目警告、全功能）→ 進 readonly：可登入、可看、可下載匯出，所有寫入 403；lockout 停用不會進一步鎖登入；期間任一天上傳新照立即回 valid。
4. 升級即生效：SaaS 後台把租戶從 Basic 改指派 Professional → 不重啟、重新整理頁面即見問卷包生效；Host 版上傳升級新照當下生效、機器未變不重跑開通。
5. 政策改版不回溯：簽發端把 grace 預設改 7 天 → 之後新照帶 7 天；存量照仍按各自照內 14 天跑完。
6. 臨時展延：展延一鍵簽出 type: extension 照（只有到期日不同）→ 上傳後服務不中斷；紀錄表標展延、不計營收。
7. 防竄改：直接編輯照檔改到期日 → 驗章失敗整張照無效、系統鎖定、本地留證（時間＋檔案指紋）；重新提供正確照恢復。
8. 時鐘回撥：把系統時間倒轉 → 偵測異常；issued_at 在未來的照被拒收。
9. 子租戶額度：開到第 6 個子租戶被擋（max_sub_tenants: 5）。
10. 補發／換綁：照檔遺失一鍵補發同照可用；換機取新機器碼 → 換綁照生效、舊指紋作廢；紀錄表事件類別正確。
11. 既有租戶 migration（DEV 驗）：跑完後全部非 root 租戶各持一張 formal 全模組照（效期約一年）、功能照常、執法路徑全量生效無特例分支。
12. root tenant 永不受限：root 在任何狀態下不受 license 守門與唯讀 gate 影響。
13. 執法總開關：環境開關關閉後，未授權模組 API 放行（上線保險絲驗證）。

九項核心設計決策的「為什麼這樣做」，供日後回頭質疑或延伸設計時對照——每項是取捨後的結論，不是唯一可行解，但都經過明確理由篩選過。

1. 簽發端獨立系統：私鑰不進產品，落地版整包程式碼在客戶手上也偽造不了照——這是整套授權體系的信任根基。私鑰若進了產品，客戶反組譯就能自己簽發，執法形同虛設。
2. 簽章不加密：防竄改是數學保證（Ed25519 簽章比對），這件事「加密」做不到也不需要——Host 版客戶持有整包程式碼，解碼邏輯終究可逆向，加密只多一層金鑰管理成本、換不到真實安全增益，反而給人「內容保密」的假安全感。防止客戶隨手翻閱內容改採打包（v2 payload zlib＋base64），跟簽章防竄改是兩件獨立的事。
3. .license armor 外皮：純外觀對齊業界慣例（JetBrains .key／GitLab .gitlab-license／Keygen PEM 風格），裸 .json 檔顯得不夠專業；PEM 文字塊格式的附帶好處是 email 轉寄不容易被郵件系統破壞格式。
4. Replace 換發制：一個租戶任一時刻只有一張現行照，續約／升級／展延一律重簽整張新照替換。好處是狀態永遠是單一真相——不用處理「模組 A 到期日跟模組 B 不同」這種疊加計算的複雜度，客服與客戶理解成本都低。
5. 到期漸進管線（notify → grace → readonly）：終態設計成永久唯讀、可登入可查看可匯出，不鎖登入。理由：續約談判時客戶資料仍在手上、公司有底氣好好談而不是被指控「扣押資料」；客戶資料不被綁架也降低法務糾紛風險——業界（GitLab／Atlassian／Elastic）做法一致，不是我們獨創的冒進設計。
6. 執法帶總開關：整組執法邏輯可由一個環境變數整體關閉。理由是上線初期若誤擋到真實客戶（例如模組分層盤點漏了什麼），可以立刻整體熄火止血，不需要走回滾版本這種慢且風險更高的路徑。
7. root tenant 永久豁免＋開通端點豁免唯讀：兩個豁免防的是兩種不同的死鎖——root 若受 license 管控，公司自己都可能被鎖出系統；唯讀狀態若連 License 上傳端點都擋，租戶會陷入「唯讀了就再也無法上傳新照解除唯讀」的無法自救狀態。
8. 機器指紋只在 Host 版綁：SaaS 環境系統本身就在公司自己機房，不需要額外綁機器；Host 版照跟著客戶硬體走，綁指紋是為了防止「一張照複製到多套部署」。
9. 模組授權沿用既有 capability 粒度：license 的模組語彙直接對齊既有權限系統的 capability.resource_type（35 個），不另建一套 license 專屬語彙。好處是商務重組（把某模組換包、調整 Plan 內容）零工程成本，只有新增全新的授權粒度時才需要產品端補守門。實作期發現這個原則有個例外：TENANT_ADMIN_EXCLUDED_RESOURCE_TYPES（見 §3）管的是「開通租戶時預設給不給這個能力點」，跟 license 管的「這個租戶商務上買了沒買」是不同維度的兩件事，不能簡單合併退役（詳見 CM-1126 裁決）。