設計 v2.0（定稿）：正式發版、直接部署、測試版發布三條路

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  actor P as 決策者
  participant G as 188 CI
  participant U as 更新站
  participant M as 決策者 Mac
  P->>G: 手動執行 pipeline
  G->>G: 建置、打包、上傳 R2
  G->>U: 登記草稿（CI token，未簽章）
  P->>M: guidant-release publish <版號>
  M->>M: 讀取私鑰（passphrase）、簽署清單
  M->>U: 送回已簽章清單，草稿轉為公開

%%{init: {'theme':'base','themeVariables':{'darkMode':false,'background':'#FBFCFC','primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','secondaryColor':'#EEF2F3','tertiaryColor':'#FBFCFC','lineColor':'#4A5A5C','textColor':'#14201F','titleColor':'#14201F','edgeLabelBackground':'#FBFCFC','clusterBkg':'#F6F7F5','clusterBorder':'#C7D1D2','fontSize':'18px'},'flowchart':{'useMaxWidth':false}}}%%
flowchart LR
  P["決策者"]
  subgraph cloud["雲端"]
    GL["GitLab<br/>pipeline、ID token 簽發"]
    US["更新站<br/>Worker＋D1"]
    R2[("R2<br/>安裝包")]
  end
  subgraph lan["公司內網"]
    B["188 建置主機<br/>runner、五個 repo、編譯鎖"]
    V["172 Vault<br/>簽章金鑰、建置期憑證"]
    N["171 Nexus／Harbor"]
    L["189 License Center<br/>防竄改簽章私鑰"]
    I["內部三台<br/>190／188 STG／189 POC<br/>正式＋測試公鑰"]
  end
  C["客戶主機<br/>只有正式公鑰"]
  P -->|選 tag 或 branch 執行 pipeline| GL
  B -->|領取 job| GL
  B -->|ID token 登入、請求簽署、讀取憑證| V
  V -->|取 JWKS 驗 ID token| GL
  B -->|裝套件、推映像| N
  B -->|送防竄改清單簽署（防安裝後程式被改）| L
  B -->|上傳安裝包| R2
  B -->|登記版本、發布（Cloudflare Access 服務憑證）| US
  B -->|直接部署：install.sh| I
  I -->|檢查更新：已發布＋內部草稿| US
  C -->|檢查更新：只有已發布| US
  I -.->|下載| R2
  C -.->|下載| R2
  style V fill:#FDECEC,stroke:#B42318,color:#7A1A12
  style L fill:#FDECEC,stroke:#B42318,color:#7A1A12

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  actor P as 發版人
  participant G as GitLab 正式發版 pipeline（188 runner）
  participant F as FE pipeline（188 runner）
  participant V as Vault（192.168.50.172）
  participant L as License Center（189）
  participant H as Harbor／R2
  participant U as 更新站
  participant T as 190 測試機
  participant C as 客戶主機
  P->>G: Run pipeline，選受保護 tag v1.29.0（pipeline=release，可填 rehearse／rehearse_base／fe_ref）
  G->>G: verify：確認受保護 tag、同步 188 工作樹、守衛測試、pytest、原始碼與相依套件弱點掃描
  G->>F: 觸發 FE pipeline（strategy: mirror）
  F-->>G: FE 映像建於 188 本機（tag 帶 FE commit），並推 Harbor
  G->>V: 以 ID token 登入（role=release-ci），讀取 License Center／Harbor／R2／更新站憑證
  G->>G: Nuitka 編譯（188 編譯鎖）
  G->>L: 送防竄改清單簽署（FR-064）
  L-->>G: 清單簽章
  Note over G,L: 防竄改：程式啟動時逐檔比對雜湊，被改過就拒絕啟動
  G->>G: BE／init／classifier 映像、取本機 FE 映像
  G->>G: 檢查版本說明：release note 檔尾要有「更新中心顯示文字」三段，缺就停
  G->>G: 映像弱點掃描（Trivy、Grype）：有白名單外的 Critical 漏洞就停
  G->>G: 打包：映像＋安裝腳本＋設定 → 客戶安裝用的 guidant-ai-<版號>.tar.gz
  opt 發版人勾選 rehearse
    G->>T: 演練：清機、安裝 rehearse_base 版、匯入 STG 資料、以新包升級、比對筆數
    T-->>G: 升級成功
  end
  G->>H: 推映像（tag 帶 commit）、上傳安裝包
  G->>V: transit/sign guidant-release（canonical 清單）
  V-->>G: 簽名（私鑰不離開 Vault）
  G->>U: 登記版本：已簽章清單＋版本說明三段
  G->>U: 發布（GitLab ID token）
  U->>U: 核：BE 專案、受保護 tag、tag＝v＋版號、kid 為印章表 primary／backup
  U-->>G: published
  C->>U: 檢查更新
  U-->>C: 1.29.0（正式金鑰簽章）

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  actor D as 開發者
  participant G as GitLab 直接部署 pipeline（188 runner）
  participant F as FE pipeline（188 runner）
  participant V as Vault（192.168.50.172）
  participant L as License Center（189）
  participant I as 目標主機（190、188 STG 或 189 POC 其中一台）
  D->>G: 任一 branch，pipeline=deploy，target 選一台（e2e／stg／poc）；可選 skip_be、reuse_bundle
  alt reuse_bundle
    G->>G: 取 188 上同版號既有安裝包
  else skip_be
    G->>G: 同步 188 工作樹；沿用 188 上同版號 BE 映像
    G->>F: 觸發 FE pipeline
    F-->>G: FE 映像建於 188 本機
    G->>G: 打包（不掃描、不檢查正式公鑰）
  else 一般
    G->>G: 同步 188 工作樹
    G->>F: 觸發 FE pipeline
    F-->>G: FE 映像建於 188 本機
    alt 188 已有本次程式內容的 BE 映像（標記 src-<commit>）
      G->>G: 沿用，不重新編譯
    else 程式有改
      G->>V: 以 ID token 登入（role=test-ci），讀取 License Center 憑證
      G->>G: Nuitka 編譯（188 編譯鎖）
      G->>L: 送防竄改清單簽署（FR-064）
      L-->>G: 清單簽章
      Note over G,L: 防竄改：程式啟動時逐檔比對雜湊，被改過就拒絕啟動
    end
    G->>G: BE／init／classifier 映像、打包（不掃描、不檢查正式公鑰）
  end
  opt target＝poc
    G-->>D: 停在部署 job，等待按 ▶
    D->>G: 按 ▶ 確認
  end
  opt 目標為 STG 或 POC
    G->>I: 停 api／socketio／worker；確認現行授權 kid 在新版公鑰表內
  end
  G->>I: scp 安裝包、install.sh --upgrade --force
  I-->>G: 升級結果

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  actor D as 開發者
  participant G as GitLab 測試版發布 pipeline（188 runner）
  participant V as Vault（192.168.50.172）
  participant L as License Center（189）
  participant H as R2
  participant U as 更新站
  participant I as 內部主機（190／188 STG／189 POC）
  D->>G: 任一 branch，pipeline=test-release，版號須為 X.Y.Z-beta.N（可選 skip_be、fe_ref、note）
  G->>V: 以 ID token 登入（role=test-ci），讀取 License Center／R2／更新站憑證
  G->>G: 同步 188 工作樹、觸發 FE；BE 映像同直接部署（src- 標記命中或 skip_be 時不重編）
  opt 重新編譯 BE
    G->>L: 送防竄改清單簽署（FR-064）
    L-->>G: 清單簽章
  Note over G,L: 防竄改：程式啟動時逐檔比對雜湊，被改過就拒絕啟動
  end
  G->>G: 映像、打包（不掃描、不檢查正式公鑰）
  G->>H: 上傳安裝包
  G->>V: transit/sign guidant-test
  V-->>G: 測試金鑰簽名
  G->>U: 登記版本：測試金鑰簽章清單＋版本說明（note，或 release note 檔尾，或空白）；內部清單自動帶入
  Note over U: 草稿，只有內部三台看得到；測試金鑰的版本不可發布
  D->>I: 到要測的那台更新中心，按「更新到 X」
  I->>U: 檢查更新、取得下載網址
  I->>H: 下載安裝包
  I->>I: 以本機測試公鑰驗章、八步升級（失敗自動退回）
  I->>U: 回報升級結果

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  actor P as 發版人
  participant G as GitLab Agent 正式發版 pipeline（188 runner）
  participant V as Vault（192.168.50.172）
  participant L as License Center（189）
  participant H as Harbor／R2
  participant U as 更新站
  participant T as 190 測試機
  participant M as 客戶主系統
  participant A as 客戶 Agent
  P->>G: Run pipeline，選受保護 tag v1.6.0（pipeline=release，可填 rehearse／rehearse_base／fe_ref）
  G->>G: verify：同步 188 工作樹、守衛測試、pytest、相依套件弱點掃描
  G->>G: build：主控台前端（FE console-dist）、Nuitka 編譯（188 編譯鎖）
  G->>V: 以 ID token 登入（role=release-ci），讀取 License Center／Harbor／R2／更新站憑證
  G->>L: 送防竄改清單簽署（FR-064）
  L-->>G: 清單簽章
  Note over G,L: 防竄改：程式啟動時逐檔比對雜湊，被改過就拒絕啟動
  G->>G: 建 Agent 映像
  G->>G: 映像弱點掃描（Trivy、Grype）：有白名單外的 Critical 漏洞就停
  G->>G: 打包：映像＋compose 設定＋安裝腳本 → 客戶安裝用的 guidant-agent-compose-<版號>.tar.gz
  G->>G: 檢查版本說明：RELEASE_NOTES.md 要有這一版的條目，缺就停
  opt 發版人勾選 rehearse
    G->>T: 演練：清除 Agent、安裝 rehearse_base 版、放入帶資料的 agent.db、以新包升級
    T-->>G: 新容器 healthy、schema_version 到最新、資料筆數不變
  end
  G->>V: transit/sign guidant-release
  V-->>G: 簽名
  G->>G: 產離線檔 guidant-agent-1.6.0.offline.tar.gz（安裝包＋簽好的清單＋雜湊，包成一個檔）
  G->>H: 推映像；上傳 agent/v1/1.6.0/（安裝包、清單、雜湊、離線檔）
  G->>U: 登記版本（product=agent）＋版本說明
  G->>U: 發布（GitLab ID token）
  U-->>G: published
  M->>U: 查 Agent 線，看到 1.6.0
  Note over M,A: 管理員在主系統更新中心 Agent 區按更新，或 Agent 主控台按「更新到 1.6.0」
  M->>H: 下載 Agent 安裝包、驗章、核雜湊
  M->>A: 推送 POST /update
  A->>A: 下載包、寫升級單；Agent 主機升級、健康檢查，回報結果

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  actor D as 開發者
  participant G as GitLab Agent 直接部署 pipeline（188 runner）
  participant V as Vault（192.168.50.172）
  participant L as License Center（189）
  participant I as 目標 Agent 主機（190、188 STG 或 189 POC 其中一台）
  D->>G: 任一 branch，pipeline=deploy，target 選一台（e2e／stg／poc）；可選 reuse_bundle
  alt reuse_bundle
    G->>G: 取 188 上同版號既有 compose 安裝包
  else 一般
    G->>G: 同步 188 工作樹、主控台前端、Nuitka 編譯
    G->>V: 以 ID token 登入（role=test-ci），讀取 License Center 憑證
    G->>L: 送防竄改清單簽署（FR-064）
    L-->>G: 清單簽章
  Note over G,L: 防竄改：程式啟動時逐檔比對雜湊，被改過就拒絕啟動
    G->>G: Agent 映像、compose 安裝包（不掃描）
  end
  opt target＝poc
    G-->>D: 停在部署 job，等待按 ▶
    D->>G: 按 ▶ 確認
  end
  G->>I: scp 安裝包、核 sha256
  G->>I: guidant-agent-compose upgrade <包>
  I-->>G: 整個 Agent compose 專案轉為 healthy

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  actor D as 開發者
  participant G as GitLab Agent 測試版發布 pipeline（188 runner）
  participant V as Vault（192.168.50.172）
  participant H as R2
  participant U as 更新站
  participant M as 內部主系統（190／STG／POC）
  participant A as 該主機的 Agent
  D->>G: 任一 branch，pipeline=test-release，版號須為 X.Y.Z-beta.N（可選 fe_ref、note）
  G->>G: 同步 188 工作樹、主控台前端、Nuitka、防竄改清單簽署（License Center）、Agent 映像、compose 安裝包（不掃描）
  G->>V: 以 ID token 登入（role=test-ci），讀取 R2／更新站憑證
  G->>H: 上傳 agent/v1/<版號>/
  G->>V: transit/sign guidant-test
  V-->>G: 測試金鑰簽名
  G->>U: 登記版本（product=agent）；內部清單自動帶入三台
  Note over U: 草稿，只有內部三台的主系統看得到；測試金鑰的版本不可發布
  D->>M: 到該主系統更新中心 Agent 區，選 Agent，按更新
  M->>U: 查 Agent 線、取得下載網址
  M->>H: 下載 Agent 安裝包
  M->>M: 以本機測試公鑰驗章、核雜湊
  M->>A: 推送 POST /update
  A->>A: 下載包、寫升級單；Agent 主機升級、健康檢查
  A-->>M: 回報每步進度與結果

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','lineColor':'#4A5A5C','textColor':'#14201F','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#F6EBD5','labelBoxBorderColor':'#9C6B12','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF','fontSize':'20px'},'sequence':{'actorFontSize':20,'messageFontSize':19,'noteFontSize':18,'actorMargin':60,'messageMargin':42,'boxMargin':12,'useMaxWidth':false}}}%%
sequenceDiagram
  autonumber
  participant G as GitLab
  participant J as 188 上的 CI job
  participant V as Vault（192.168.50.172）
  G->>J: 啟動 job，附 ID token（aud＝Vault 網址，含 project_path、ref_type、ref_protected、user_id）
  J->>V: POST auth/jwt/login（ID token、role）
  V->>G: 取 JWKS 驗 ID token 簽章
  V->>V: 核 bound_claims：專案、ref 類型、受保護、user_id
  V-->>J: 短效 token（30 分鐘）
  J->>V: GET kv/data/ci/*（依角色 policy）
  J->>V: GET transit/keys/<鑰名>（比對 CLI 釘住的公鑰與 kid）
  J->>V: POST transit/sign/<鑰名>
  V-->>J: 簽名
  J->>V: POST auth/token/revoke-self