FR-172 · 設計文件 v1.1 · 2026-11-03 · 實作中異動
對照 v1.0（design.md，2026-11-01 定稿）；推翻 D9，其餘決策不變
🔴 這份只記 v1.0 定稿後、實作與 190 實測期間對設計本身做的改動。 推翻一條（D9 兩步改一步），補定六條（維護模式、主控台立即檢查、更新包清理、同版重套、測試包出包、升級中鎖畫面）。v1.0 原文保留在 design.md 不動。現況（版號、程式、流程）看 FINAL-SPEC.md。
| 版本 | 日期 | 檔案 | 內容 |
|---|---|---|---|
| v1.0 | 2026-11-01 | design.md | 定稿：決策 D1～D12、兩條版本線、一輪更新時序圖、19 張卡 10 批 |
| v1.1 | 2026-11-03 | 本頁 | 190 實測 24 條回饋後開修正案 FR-172.1（10 張卡 3 批）；推翻 D9；補定維護模式、立即檢查、更新包清理、同版重套、測試包出包、鎖畫面時機 |
v1.0 的 19 張卡做完、出 1.28.0／Agent 1.5.0 後，決策者在 190 實際升級三輪，提出 24 條回饋（handoff/190-test-feedback.md）。其中大部分是文案與版面，但有六件是設計層的：
| # | v1.0 | v1.1 | 理由 | 決策者裁示 |
|---|---|---|---|---|
| **D9（推翻） | Agent 區「預先下載 → 更新選取的台」兩步，勾選框下載完才出現 | 一步完成**：一開始就能勾選；按「更新選取的 N 台到 X」時，主系統手上沒有 X 的包就先下載（有進度、可取消），下載完自動推；「預先下載」保留為選用 | 兩步的理由（誰按、何時下載要有紀錄）改由下載稽核記按的人滿足，不必拆兩步 | 2026-11-03 |
| 補定 | — | 「手上有包」不等於「手上是最新」：判斷能不能直接推，要比「手上的包」與「上次檢查到、相容的最新版」，手上較舊就先下載。Agent 主控台回「有沒有新版」也用同一個判斷 | 主系統留著舊包時，只看「有沒有包」會拿舊包推，每台都回「沒有落後」 | 2026-11-03（190 實測） |
| 補定 | — | 下載中再有人按更新，併進待推清單、不覆蓋：每筆各記自己的台、排程時間與操作者，下載完逐筆推 | 覆蓋的話，更新中心勾 5 台下載中、Agent 主控台按 1 台，5 台就不會被推 | 2026-11-03（自動資安檢查） |
| 補定 | — | Agent 升級中＝維護模式：一收到 /update（含下載中、等工作做完、主機在跑）就停收新工作；主控台整頁鎖住只顯示進度，完成自動恢復、不必重新登入（session 落地） |
升級中還能派工、主控台還能點，換容器時斷線 | 2026-11-03 |
| 補定 | — | 主控台「立即檢查」＝請主系統當下查更新站（全機 5 分鐘節流）；與主系統斷線時只給離線上傳 | 新版發布後主控台仍說「已是最新」 | 2026-11-03 |
| 補定 | v1.0 D7：保留「各台最舊＋最新」兩份，下載時才清 | 整批推送全部成功後就清用不到的 Agent 包；主系統自己升級成功後 incoming/ 只留清單（重試會重新下載） |
兩版包各 1.7 GB 一直佔著 | 2026-11-03 |
| 補定 | — | 測試機同版重套：兩個開關都開才放行——主系統 PRODUCT_UPDATE_ALLOW_SAME_VERSION=1（guidant.env，主機升級腳本也讀）、Agent AGENT_UPDATE_ALLOW_SAME_VERSION=1（Agent .env，compose 轉進容器，主機升級腳本也讀）；降版、跨主版號照擋；任何出貨範本都不放這兩個鍵 |
測試機升到最新後要能重看升級流程，不必一直出新版 | 2026-11-03 |
| 補定 | — | SeaweedFS 兩個容器 init: true（docker 的 tini 當 PID 1 收殭屍），pids_limit 留作保險 |
PID 1 是 weed 不收殭屍 | 2026-11-03 |
| 補定 | — | 內部測試包略過 SBOM 與弱點掃描：主系統綁 --skip-prod-key-check、Agent 用 --internal-test；正式包不帶就一定會掃，沒有單獨關掉掃描的旗標 |
測試包每次多等約 9 分鐘 | 2026-11-03 |
| 補定 | — | 主系統發動更新時，開著的 Agent 主控台最慢 30 秒才鎖（主控台平常 30 秒問一次狀態）；在主控台自己按的當下就鎖 | 要即時就得做 Agent 主動推給瀏覽器的通道，划不來 | 2026-11-03「先這樣」 |
v1.0 其餘決策（D1～D8、D10～D12、Agent 不連外網、不做舊客戶過渡）一條都沒有推翻。
v1.0 的 19 張卡（CM-3402～3420）全部完成。修正另開獨立母卡 CM-3469（FR-172.1），不掛在 CM-3401 底下（工作坊只派「母卡欄為空」的卡）：
| 批 | 卡 | Repo | 做什麼 |
|---|---|---|---|
| 1 | F-1 CM-3470 | Agent | SeaweedFS init: true |
| 1 | F-2 CM-3471 | BE | 一步更新（沒包先下載再推）、下載進度、整批成功清包、主系統升級成功只留清單 |
| 1 | F-3 CM-3472 | FE | 更新中心文案、全頁遮罩、升級完返回不白畫面、更新紀錄可下載升級 log |
| 1 | F-4 CM-3473 | Agent | 升級中停收工作、session 落地免重登、立即檢查請主系統查站 |
| 2 | F-5 CM-3474 | FE | Agent 區一開始可勾、一步更新、下載進度與取消、按鈕排版同主系統 |
| 2 | F-6 CM-3475 | FE | Agent 主控台更新頁改版、全視窗鎖定、斷線只給離線上傳 |
| 2 | F-7 CM-3476 | BE | Agent 升級中標記、主控台立即檢查端點（節流）、每台步驟、主系統升級成功可下載 log |
| 3 | T-1 CM-3477 | BE | 同版重套（主系統端）＋主機升級單讀開關 |
| 3 | T-2 CM-3478 | Agent | 同版重套（Agent 端）＋主機升級單讀開關＋compose 轉傳開關 |
| 3 | T-3 CM-3479 | FE | 三處「重新套用」按鈕 |
190 實測又抓到的三件（主系統留舊包推不出去、主控台同根因、8444 握手卡住導致強制重新整理沒 CSS）併在 F-2、F-6、F-4 的範圍內修，沒有另開卡。
| 主系統 | Agent | |
|---|---|---|
| v1.0 預定 | 1.28.0 | 1.5.0 |
| 實際出到 | 1.28.3 | 1.5.5 |
| 中間版用途 | 1.28.1 只換版號測升級；1.28.2 FR-172.1 批 1～2；1.28.3 批 3＋190 實測修正 | 1.5.1、1.5.2 只換版號測升級；1.5.3 批 1～2；1.5.4 批 3；1.5.5 主機升級單同版放行 |
全部是內部測試包、測試章簽。正式章／Vault 簽的第一版留給 FR-173（1.29）。
--internal-test，不要另開同義旗標；主系統封包已改多核壓縮、釘版第三方 image 匯出檔以 image ID 快取，CI runner 要把 .build/image-cache/ 放在持久目錄才有效。/update 端點）。