循序圖

%%{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
    autonumber
    participant SCH as 排程
    participant BE as BE
    participant US as 更新站
    participant ADM as 管理員
    participant FE as FE
    participant WK as Worker
    participant R2 as R2
    participant H as 主機
    SCH->>BE: 每 6 小時（與啟動時一次）run_scheduled_check
    BE->>US: POST /v1/check（授權檔、指紋、現行版）
    US-->>BE: none，或 available＋path＋每段 signed_manifest
    BE->>BE: 每段用本機印樣驗章、版號遞增、主版號、min_base_version
    BE->>BE: 寫 last_check（系統設定）
    BE-)ADM: 新的一版才寄信（同一版不重寄）
    ADM->>FE: 開更新中心
    FE->>BE: GET /system/product-update/status
    ADM->>FE: 按「下載」或「更新到 X」
    FE->>BE: POST /download 或 POST /apply
    BE->>BE: 建紀錄 downloading，入列背景工作
    WK->>BE: 撿單 product_update_download
    loop 路徑每一段
        WK->>US: POST /v1/download-url（version）
        US-->>WK: 15 分鐘預簽網址＋sha256＋size
        WK->>R2: GET（Range 續傳）寫 incoming/*.tar.gz.part
        WK->>WK: 大小與 sha256＝清單才改名
        WK->>US: POST /v1/download-url（artifact=ops），拿得到才下
    end
    WK->>BE: 紀錄改 ready、記下載速率
    alt 按的是「更新到 X」
        WK->>H: 直接寫更新單（接圖 2）
    else 只按了下載
        WK->>H: 寫 preflight 單到 orders/
        H->>H: 只跑第 1 步，寫進度檔 status=preflight
    end
    FE->>BE: 每 3 秒 GET /status，看到 ready 與預檢結果

%%{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
    autonumber
    participant ADM as 管理員
    participant FE as FE
    participant BE as BE
    participant SD as 主機 systemd
    participant RN as 主機 runner
    participant FD as 前門
    participant SCH as 排程
    participant US as 更新站
    ADM->>FE: 按「立即更新」（勾或不勾 Agent 跟進）
    FE->>BE: POST /system/product-update/apply
    BE->>BE: 每段重驗包、紀錄 scheduled、記 job_id
    BE->>SD: 寫 orders/{job_id}.json（暫存再 rename）
    SD->>SD: path 單元觸發 upgrade --from-order
    SD->>SD: 讀單、每段重驗包
    SD->>RN: 交給 upgrade_runner.sh incoming 的包
    RN->>RN: 第 0 步 驗包、換成新版維運指令、exec 新版
    RN->>RN: 第 1 步 預檢
    RN->>RN: 第 2 步 寫 draining，等工作做完
    RN->>RN: 第 3 步 停服務、複製資料庫到 pgdata-next
    Note over FD: 後端停了，前門送維護頁、讀進度檔
    RN->>RN: 第 4 步 載映像、以複本起 db、migrate
    RN->>RN: 第 5 步 以複本起受檢 api、實打
    RN->>RN: 第 6 步 換接、起新版、寫 succeeded、寫 last-switch.json
    RN->>FD: 最後重建前門
    FD-->>ADM: 維護頁看到 succeeded、api 通了，帶 ?upgraded=1 回去
    RN->>RN: 第 7 步 清理
    SCH->>BE: 每分鐘讀進度檔
    BE->>BE: 紀錄 succeeded、清舊 last_check、重查新版
    BE->>US: POST /v1/report（result=succeeded）
    BE->>BE: 每步補寫 system_logs

%%{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
    autonumber
    participant SCH as 排程
    participant BE as BE
    participant AG as Agent
    participant AH as Agent 主機
    participant US as 更新站
    SCH->>BE: 每分鐘 tick（進度檔 succeeded、to＝現行版）
    BE->>BE: 建跟進列：第 1 批 1 台 dispatched、其餘第 2 批 pending
    BE-)AG: POST /update/notify（叫它立刻心跳）
    AG->>BE: POST /agents/heartbeat
    BE-->>AG: data.update＝target_version、bundle_sha256、size
    AG->>BE: GET /agents/update/bundle（續傳）
    AG->>AG: 驗大小與 sha，寫 agent-upgrade-order.json
    AH->>AH: path 單元觸發 upgrade-host order
    AH->>AH: 包搬進 staging、驗 sha、安全解包、載映像、舊版驗新版章
    AH->>AH: install.sh upgrade（1 預檢、2 停接、3 換設定、4 重建容器、5 健康、6 清理）
    AH->>AH: 寫 Agent 進度檔（同 job_id）
    AG->>AG: 下次心跳前讀進度檔
    AG->>BE: 心跳帶 upgrade_result（succeeded 或 failed）
    BE->>BE: 跟進列改 succeeded 或 failed
    SCH->>BE: 下一分鐘 _advance
    BE->>BE: 前一批全成功放下一批；有失敗其餘 paused
    SCH->>US: POST /v1/report（target=agent），送達才記 reported_at

%%{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
    autonumber
    participant CI as CI
    participant US as 更新站
    participant R2 as R2
    participant DEC as 決策者
    participant CLI as CLI
    participant IN as 內部先裝主機
    participant BE as 客戶主系統
    CI->>CI: rehearse-upgrade（同一支 build_bundle.sh 打包、排練升級）
    CI->>CI: package：SBOM 門檻、build_bundle.sh、推 Harbor
    CI->>US: POST /admin/releases/register-draft（CI token）
    US-->>CI: 201 draft＋R2 key（bundle、sha256、manifest）
    CI->>R2: 上傳包、.sha256、release.json（未簽）
    DEC->>US: 後台 PUT internal-targets（內部先裝指紋）
    IN->>US: POST /v1/check（草稿只回給名單內的機器）
    IN->>IN: 照圖 1、圖 2 升級
    IN->>US: POST /v1/report（succeeded）
    DEC->>CLI: guidant-release publish {版}
    CLI->>US: GET /admin/releases/{版}（取草稿與內部先裝結果）
    CLI->>CLI: 檢查全部成功、確認、私鑰蓋章、用印樣驗自己的章
    CLI->>US: POST /admin/releases/{版}/publish（signed_manifest、kid）
    US-->>CLI: published
    BE->>US: POST /v1/check
    US-->>BE: available＋signed_manifest
    BE->>BE: 用本機印樣驗章（接圖 1）