落地版 Installer 設計定案

狀態：設計定案（D1–D12 已拍板；D13 大半收斂 2026-08-17；餘 D11.3（樣板 SSP，PM 議）開放）｜建立日期：2026-08-16｜母案：CM-1189 FR-065 Installer 前作：FR-063 Nuitka 落地版打包 design（image 1.14.0 出貨）／FR-064 防竄改偵測與授權鎖定 design（34 卡 Done） 討論稿（唯一內容真相源，含 e2e-env 借鑑全文與 D 項拍板脈絡）：discussion.html｜DB init 細節引用源：db-init-inventory.html（CM-1207）

1.1 背景

本案是落地版三階段戰線的第三棒：FR-063 把 BE 編成不帶原始碼的 Nuitka image、FR-064 給了它防竄改與授權鎖定——「跑起來之後」的問題已解完。還沒解的是「怎麼跑起來」：

1. 客戶側安裝資產現況＝零。唯一安裝素材是 docker/production/docker-compose.yml＋deployment-env.md §0 四步手動流程，寫給自己人不是客戶。
2. DB 從零建庫沒有機制。186 張表、107 條 RLS policy、5 個 schema、一票必備 seed，全靠 DEV 這顆活了兩年的庫（CM-1207 已盤點完整清單）。
3. FE 沒有落地交付形態。正式部署至今是 zip dist scp 手工擺放。
4. image 沒有交付通路。build_image.sh 不含 push／save；Harbor 是內部 registry，air-gapped 客戶碰不到。
5. 升級／回滾整段空白。換版只有「改 GUIDANT_VERSION 重跑 up -d」一句。

目標：一份出貨 bundle＋一支 installer，客戶自己（或一般 IT 人員照手冊）完成安裝、開通、日後升級，不依賴原廠工程師到場。硬前提承 FR-064 部署假設：客戶環境可能完全 air-gapped，一切須離線自洽。

1.2 首次安裝＋開通流程

安裝與開通有「雞生蛋」結構：license 綁機器指紋（sha256(/etc/machine-id)），但取指紋的唯一現成介面需 JWT 登入——所以旅程必須在裝機當下就把指紋交到客戶手上：主展示面是 Web 設定精靈頁（D10），installer fingerprint 為保底（D6）。

%%{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 V as 原廠（build＋LC 簽發站）
    participant C as 客戶安裝者
    participant H as 客戶主機
    participant S as Guidant AI 服務

    V->>C: 出貨 bundle（install.sh＋image tars＋bundle manifest＋SQL/seed＋手冊）
    C->>H: 解開 bundle，執行 install.sh
    H->>H: 環境檢查（docker/compose 版本、/etc/machine-id 非空、磁碟/記憶體）
    H->>H: docker load 各 image ＋ 比對 bundle manifest digest（D3）
    H->>H: 產生基礎設施密碼組（cmmgr/cm_app）＋ 寫 guidant.env
    H->>H: DB init（one-shot init 容器跑分段腳本：schema＋字典 seed，不建 admin，D4）
    H->>S: docker compose up -d（PG/Redis/BE api/BE socketio/FE，D1/D2）
    S-->>H: healthcheck 全綠
    H-->>C: 印出：「請開 http://<主機>/ 完成設定」＋ 一次性 setup token（D10）
    C->>S: 開站進 Web 設定精靈：貼 setup token → 建 admin 帳號（密碼自設）
    S-->>C: 精靈顯示機器指紋（sha256 machine-id，D6）＋ license 匯入引導
    C->>V: 抄指紋（離線通路：mail／電話）申請簽照
    V->>V: LC 簽發站簽 license（綁指紋）
    V-->>C: 回傳 .license 檔（PEM armor）
    C->>S: 在精靈匯入 license（復用 FR-062 開通頁）→ 完成安裝進登入頁
    S-->>C: 開通完成，全功能可用

1.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'}}}%%
sequenceDiagram
    participant V as 原廠
    participant C as 客戶安裝者
    participant H as 客戶主機
    participant D as PostgreSQL

    V->>C: 升級 bundle（新版 image tars＋增量 migration＋manifest）
    C->>H: 執行 install.sh --upgrade
    H->>D: ① pg_dump 全量備份（落地到指定備份目錄）
    H->>H: ② docker load 新 image ＋ digest 驗證
    H->>D: ③ one-shot init 容器套增量 migration（依 schema_migrations 判斷起點，align_migrations 演算法移植）
    H->>H: ④ 改 GUIDANT_VERSION → docker compose up -d（自動 recreate）
    H-->>C: healthcheck 全綠，升級完成
    Note over C,D: 回滾＝restore 備份 ＋ GUIDANT_VERSION 回舊 tag 重跑 up -d

整案一句話：把前兩案的產物（編譯好的 image＋防竄改機制）包成「客戶拿到一包東西，自己裝得起來、開得了通、升得了版」的落地安裝方案。

依賴：.1→.2→.3→.5→.4 直線。決策者功課：.2 前裁 D11.2/D11.5＋備 CMMC 初始化資料、.3 前公司議 root 介面硬擋與否。

2026-08-16 批次拍板：D1–D10／D12 全數定案；D11 十子項 8 定案 2 保留；D13 待公司討論。定案一字內容以討論稿 callout 原文為準，本表為設計文件形狀的收斂。

2.1 D11 子項裁決表（seed 出貨範圍，承接 CM-1207 §3.4）

字典類必備 seed（operations／system_menus／ui_routes／capabilities／root tenant+org／Administrator 角色／RUNTIME_CONFIG 等，CM-1207 §3.1）已明確屬出貨集，不在此重列。

3.1 元件 × 現況 × 本案動作

3.2 e2e-env 借鑑要點

test repo compliance-manager-test/e2e-env/ 的 8-service 全套 compose 每天在驗證「這組服務能在一個 compose 內良好共處」。user 指示：分析借用、不整抄——借拓撲與機制三條線（服務組成／互連／啟動順序），不借資料來源、image 血統、測試編排三條線。可移植 12 項：

不可抄清單（golden dump／roles 搬遷／sanitize／mailpit／E2E image／ENV=DEVELOP_PREMISE／兩層疊 image／測試編排產物）詳見討論稿〈e2e-env 借鑑分析〉。

4.1 產品 compose 全 stack（D1／D2）

服務拓撲（service 名用中性名，不沿用 e2e 的 e2e-postgres 類寫死名）：

設計要點：

• 與既有 BE compose 定式的關係：docker/production/docker-compose.yml 的 7 個掛載（static/log/home/tmp/pki/machine-id/agent 憑證）、read_only＋tmpfs、宿主 /etc/machine-id 掛載（CM-1242 指紋修復）全數保留，本案是擴充不是重寫。
• 啟動順序：depends_on condition: service_healthy 鏈——DB/Redis healthy→BE 兩服務→FE。
• nginx.onprem.conf（以 nginx.e2e.conf 為底、upstream 指向 compose service 名）：同源反代 /api/1.0→guidant-api:8000、/socket.io→guidant-socketio:8002（含 WS upgrade）；resolver 127.0.0.11 valid=10s＋變數 upstream；client_max_body_size 0、API read_timeout 600s＋buffering off、socket.io 3600s；SPA try_files。
• HTTPS 443＋憑證掛載是必要設計（bind ro、私鑰不進 image）：非 secure context 下 crypto.randomUUID() 為 undefined、登入卡死零訊息——不是資安加分項，是功能必要（§3.2 第 12 項）。
• 自備 DB/Redis 引導：compose 內寫註解——改 DB_HOST／REDIS_HOST 環境變數、移除對應 service 段；installer 不做參數化外接模式（D1）。
• recreate 風險防護：傾向 DB/Redis 獨立成另一個 compose project（或至少檔內大字警語＋installer 包裝所有 up 指令永遠帶 service 名），不讓客戶裸打 up -d。
• port 分離：服務互連走 service 名＋容器內 port，對外映射另計——客戶主機 port 衝突只改映射。
• .env 範本：零硬編憑證，只列 key 與用途；§3.2 第 10 項踩坑清單照單全收（ENABLE_MULTI_TENANT="true" 顯式、兩支加密 key、DB_PORT=5432 顯式）。

4.2 FE production image（D2）

• 新增 nginx.onprem.conf；Dockerfile 既有 ARG NGINX_CONF 換入；build 用 build:PRD（相對路徑產物，同源即可用，不需 per-customer rebuild）。
• 進 build 管線：FE image build 併入 scripts/build/ 管線，tag 與 BE 同版號（guidant-ai-fe:<X.Y.Z>）。
• 實作棒查清事項：VITE_DEV_MODE（PRD 現值 true——語意與影響面查清後定值，落地版直覺上不該開）與 VITE_TURNSTILE_SITE_KEY（現值 Cloudflare 測試 key，與 D8 停用連動）。

4.3 bundle 打包與交付（D3／D7）

• bundle 內容：install.sh＋全部 image 的 docker save tar（BE/FE/PG/Redis，MinIO 隨選配）＋bundle manifest（各 tar sha256 digest＋適用起始版號區間）＋SQL init 腳本與 seed 檔（框架與檢測 Profile 於 2026-08-21 起皆走「原廠匯好進基線」，資料列在 04/05、檔案實體走 storage-seed；D11.1／D11.4 改版）＋manifest.tsv＋客戶手冊。
• 完整性驗證：installer docker load 後逐一比對 manifest digest，不符即拒裝——確保客戶手上的 image 與原廠出貨一致（FR-064 D7 劃入項）。cosign 列評估項不在 v1。
• Harbor pull 替代路徑：僅文件化，限有網且信任外連的客戶。
• PROD 簽章鑰四步（D7，出貨硬前置）：LC 端生成 PROD 鑰對→public_keys.py 新增 PROD kid→重 build image→出貨 bundle 一律以含 PROD 鑰的 image 產出。連帶 D12：進版（version-bump）與 image 推 Harbor 掛在 bundle 打包段前後執行。

4.4 DB init（D4／D11）

引用源：db-init-inventory.md §5（方案比較與共同前提全文）。

• 分段腳本組（scripts/init/）：00-cluster.sql（CREATE ROLE cmmgr 降規版／cm_app／cm_app_group、CREATE DATABASE，連 postgres 庫）→01-extensions（uuid-ossp、pg_trgm）→02-schema（DEV pg_dump --schema-only 整理：去 DEV 殘留表、去歷史月分區）→03-grants（default privileges ×5 schema＋event trigger trg_auto_grant_cm_app，不逐表 GRANT 400 行，逐項掃描僅作驗收）→04-seed-core→05-seed-catalog→06-admin（本案 D10 下不在 init 建 admin，改由精靈通道；段位保留給精靈 BE 寫入的契約參照）→99-stamp＋init.sh。
• 執行載體＝one-shot init 容器：installer 產參數（兩組 DB 密碼）→起 init 容器跑 init.sh→成功後才起服務容器（服務只拿 cm_app 憑證，cmmgr 憑證只存在建庫當下）。與升級 migration 容器共用同一形態。
• 基線真相＝DEV pg_dump，不是 224 支 migration 重放（歷史串互相覆蓋、混雜環境限定檔）。
• seed 範圍照 D11 裁決：字典類必備 seed（CM-1207 §3.1 清單）＋root tenant/org id=1 硬約定（顯式指定 id＋setval sequence）＋Administrator 角色＋RUNTIME_CONFIG＋2 支 builtin BPMN（D11.2 定案 id 1/3，兩筆 inactive 內建已砍；CM-1322 查證確認）＋stage_objects 六筆階段字典（CM-1322 補漏）；CMMC 2.0 與檢測 Profile 皆走「原廠匯好進基線」——資料列確實要 seed（D11.1 於 2026-08-17、D11.4 於 2026-08-21 先後改版；早期「不 seed、走應用層匯入」的敘述已作廢）；debug view 連 DEV 刪（D11.9，先行 migration）；DB 名 guidant_ai（D11.10）；D11.2 清單核對、D11.3/D11.5 依開放項時程補定。
• 冪等：seed 用自然鍵 ON CONFLICT DO NOTHING；schema 段以 schema_migrations baseline marker 判斷跳過；失敗語意＝整庫重建（init 場景可接受）。
• 收尾 stamp：schema_migrations 登記 __init_baseline_v<版號>__ marker＋補登已收斂的 active migration 檔名；schema_version 補基線版號——讓後續增量 migration 與三環境 diff 工具無縫接軌，基線之後的新 migration 照舊制走。

4.5 install.sh（D10）

薄終端原則：bash 只管基礎設施段，應用設定全部讓給 Web 精靈；不做 TUI。

• 環境檢查清單（宿主前提，門檻數值實作棒定案）：
  • OS：Linux x86_64（glibc ≥ 2.35——BE binary 在 Ubuntu 22.04 編出，基底鏡像自帶 glibc，此條實際約束的是 docker 本身）
  • Docker Engine（最低版本待定，需支援 compose plugin v2）＋docker compose plugin；systemctl enable docker（開機自起前提）
  • /etc/machine-id 非空：test -s /etc/machine-id 必過（CM-1242 實測：缺檔時 docker 會建成目錄、指紋退回 MAC 每次重啟漂移；極精簡系統用 systemd-machine-id-setup 補）。⚠️ machine-id 一旦重生成，既有綁機憑證全部失效——只在「本來就沒有」時補
  • 磁碟／記憶體／CPU：門檻待定（image tars＋DB volume＋上傳檔＋log＋pg_dump 備份；PG＋Redis＋gunicorn 4 workers＋socketio＋nginx 全包最低規格，實測定）
  • 時區：主機 TZ 與部署一致（image 內建 Asia/Taipei，跨時區覆寫但不可各自為政）
  • 網路：無外網前提可運作（air-gap 自洽）；對內開放單一入口 80/443
• 流程步驟：環境檢查→docker load＋digest 比對（不符拒裝）→產生基礎設施密碼組（cmmgr/cm_app 分別產生，不沿用 DEV 同密碼慣例）＋寫 guidant.env→DB init（one-shot init 容器：schema＋字典 seed，不建 admin）→docker compose up -d→healthcheck 全綠。
• 尾端印出：「請開 http://<主機>/ 完成設定」＋一次性 setup token（Jenkins 式防搶注——避免精靈開放期間被非安裝者搶先建帳號）。不印 admin 密碼（密碼由客戶在精靈自設，不經終端留痕）。
• --config 非互動模式：參數由設定檔提供，供自動化／重跑場景。
• installer fingerprint 子命令：見 §4.6。

4.6 Web 設定精靈（D6／D10）

• 未初始化偵測：首次開站偵測「無 admin」自動進入精靈；已初始化則正常登入頁。
• setup token 驗證：精靈第一步貼 install.sh 印出的一次性 token，驗過才放行後續步驟。
• 建 admin 一次性通道：繞過既有權限體系的特殊 API，用後即封——admin 建立成功後通道永久關閉。密碼客戶自設（走既有密碼政策驗證）。
• 機器指紋顯示＋複製鈕：精靈頁顯示 sha256(/etc/machine-id) 指紋——這是指紋的主展示面（D6）；客戶抄指紋走離線通路（mail／電話）向原廠申請簽照。
• license 匯入引導：復用 FR-062 開通頁——拿到 .license 檔（PEM armor）貼上匯入→完成安裝進登入頁。
• 保底工具：installer fingerprint 子命令，演算法與 machine_fingerprint.py 一字不差；裝機尾端自動印＋可隨時重跑（服務起不來時可用）；實作棒需加「installer 與 BE 兩邊算出同值」的驗證步驟。
• root tenant 命名段（🔶 2026-08-17 裁示更新）：D13 大半收斂採系統殼方案——精靈不建 root admin（root admin 由 DB init seed 建、原廠持有），此段改為「建第一個業務租戶」由客戶命名、root 顯示名固定（如 System），並加「建租戶管理員→日常用租戶管理員登入」引導（setup token 通道建立對象＝業務租戶管理員）。殘餘開放僅「root 層介面硬擋業務與否」（公司議，不阻精靈實作）。
• SMTP／storage 等不進精靈必填，裝完後台設定頁慢慢設。

4.7 升級與回滾（D5）

四步包成 install.sh --upgrade：

1. pg_dump 全量備份（落地到指定備份目錄）
2. docker load 新 image＋digest 驗證
3. one-shot init 容器套增量 migration——align_migrations.sh 的 diff＋--apply 演算法移植到客戶端形態：連線參數外部注入（現版寫死內部 IP、密碼讀 repo .env，客戶端重做連線層）、SQL＋manifest.tsv 隨 bundle 出貨、依 schema_migrations 判斷起點
4. 改 GUIDANT_VERSION→docker compose up -d（自動 recreate）

• 相容性檢查 v1 最簡版：bundle manifest 標「適用起始版號區間」，目前版本不在區間內即拒跑。
• 回滾語意：restore 備份＋GUIDANT_VERSION 回舊 tag 重跑 up -d。明文告知：回滾會丟升級後產生的資料，屬災難逃生不是常規操作。

4.8 K8s 預留設計要點（D12 裁示：本案不實作，正式預留節）

user 明示「要預留 K8s」——本案不做 cluster 實作，但以下記為未來 K8s 案的起點；compose 寫成乾淨服務契約（服務名／port／env 介面清楚）保持可翻譯性。

鎖定態排除 liveness 的設計要點：FR-064 已知，K8s liveness 下鎖定殼會 CrashLoop（compose 落地不受影響）——上 K8s 時需把「授權鎖定態」排除在 liveness 判定之外（鎖定＝業務拒服務但行程存活，不可被 kubelet 視為 unhealthy 重啟）。

cluster 化前提五條（compose→K8s 翻譯是機械工，真門檻在應用層假設，先記錄不動）：

1. 機器指紋綁單機（sha256(/etc/machine-id)）——多節點下每台指紋不同，license 模型要改（改綁 cluster identity 或浮動授權）。
2. 鎖定殼 vs liveness：如上，鎖定態排除在 liveness 判定外。
3. tamper 偵測的 FS 落點（/opt/guidant/pki、unlock.token）——多副本共享或各自持有需重新設計。
4. storage 需切 MinIO/S3：local storage 綁單機磁碟，多副本必然外部化。
5. socketio 多副本需 sticky session（或改 message-queue adapter）。

未來有真實需求另開 FR。

實況（2026-08-17）：.1／.2／.3 全數實作完成（含追補卡，T-2.5c 進行中除外）；.4 三卡未開工。2026-08-18 追加 .5（SeaweedFS 物件儲存替換，D14），插在 .3 之後、.4 之前。

依賴鏈：.1（地基）→ .2（DB init＋installer 殼＋bundle＋PROD 鑰）→ .3（精靈與升級）→ .5（SeaweedFS 替換）→ .4（文件與真機驗收，T-4.1/T-4.2 須含 .5 內容）。.1 依 D1/D2（均已定案）即可開工。開放項影響：D11.2 清單核對與 D11.5 → T-2.2（.2 開工前定）；D11.3 → T-2.2 seed 範圍（現裁「留空」可先行，與 PM 議定後若補範圍另起增量）；D13 → T-3.2 精靈流程（.3 棒實作前公司裁決）。D12 的進版與推 Harbor 屬出貨動作，掛 T-2.6 前後執行。

FR-065.1 full-stack compose（地基棒）— 依賴：無（D1/D2 已定案）

DB 先用暫行手段（如手動 restore）驗通拓撲，正式空庫 init 屬 .2。

FR-065.2 DB init＋installer 殼＋bundle＋PROD 鑰 — 依賴：FR-065.1（D3/D4/D7/D10/D11）

FR-065.3 開通精靈與升級 — 依賴：FR-065.2（D5/D6/D8/D10；D13 於本棒前裁決）

FR-065.4 文件與真機驗收 — 依賴：FR-065.3

.4 前置待收（2026-08-18 排程重整）：CM-1235（PyMuPDF AGPL 替換，出貨合規硬前置）／CM-1273＋CM-1269（install log 落檔＋系統檔修復，併棒）／CM-1275 驗收／CM-1270 真機複驗。

FR-065.5 物件儲存替換——SeaweedFS 出廠即啟用（D14，2026-08-18 追加）— 依賴：FR-065.3；.4 的 T-4.1/T-4.2 依賴本段

子需求卡：CM-1275（https://app.notion.com/p/FR-065-5-SeaweedFS-PDF-3c0346da4cd081468eede5e4e735d994）

派棒註（2026-08-18）：CM-1280（T-2.5e compose log rotation）併入本棒排最前（同動 compose 檔避免互踩）——執行序 CM-1280 → T-5.1 → T-5.2 → T-5.3。

follow-up（不擋 .4、出貨後另做）：CM-1279 儲存後端遷移工具——掃 upload_files 異型列（含 system-scope 最優先）→讀舊寫新→checksum 過才 UPDATE→冪等續跑（同 CM-1267 性質）。

追補卡（實測後追加，2026-08-17）

188 真機首測（見 §6）撞出的問題與決策者追加需求，成三張追補卡：

乾淨機器全鏈場景：

1. 裝：全新 Linux 主機解開 bundle 執行 install.sh→環境檢查過→load＋digest 驗證過→DB init 完成→up -d 全組 healthy→印出精靈網址＋setup token
2. 精靈：瀏覽器開站自動進精靈→貼 token→建 admin（密碼自設）→看到機器指紋並複製
3. 開通：指紋送原廠簽照（模擬離線往返）→精靈匯入 .license→進登入頁→登入後全功能可用（license 軸外不再 403）
4. 升級：舊版裝機後套升級 bundle --upgrade→備份→migration→recreate→healthcheck 全綠、資料保留
5. 回滾：restore 備份＋回舊 tag→系統回到升級前狀態可用

負面案：

• digest 不符拒裝：竄改任一 image tar→installer 比對失敗、明確報錯、不進入 load 後續步驟
• setup token 錯誤：精靈貼錯 token 拒入；admin 建立後一次性通道重放被拒
• machine-id 空檔偵測：/etc/machine-id 缺檔或空檔→環境檢查即擋下（不進入安裝，避免指紋漂移事故）
• 升級版號區間不符：目標主機版本不在 bundle 適用區間→--upgrade 拒跑

2026-08-17 188 真機首測紀錄

真 bundle（--skip-prod-key-check 測試包）於 188 走通全鏈：install.sh 裝機→Web 精靈建租戶與 admin→機器指紋（installer 與 BE 兩邊算出同值）→LC STG 簽照（issue→activate 離線開通）→匯照開通→功能可用。首測撞出的問題已成三張追補卡（T-2.5b/T-2.5c/T-3.2b，見 §5「追補卡」節）。

2026-08-17 首腦登記（CM-1189 母卡），決策者帶公司議，T-4.1 手冊成文前需定案：

1. ✅ AI 功能：維持開放（2026-08-18 定案）——底線不變（原廠 token 絕不進 bundle，T-2.6 出貨守門），token 於交付/裝機後配置（guidant.env／後台設定），T-4.1 手冊照此寫。後續選項（AI Key 客戶自管維護功能／初期 token 用量限制）先不做、不入本次範圍。
2. ✅ Google Drive OAuth：先沿用 Demo（測試模式）憑證出貨（2026-08-18 定案）——正式 OAuth App 申請完成後再替換，不擋出貨。air-gap 客戶模組不啟用即不外連（T-3.5 已盤點）。
3. ✅ 物件儲存 MinIO→SeaweedFS：已定案收口（2026-08-18）——五點拍板見 D14，工程落地開卡 FR-065.5（CM-1275～1278）＋遷移工具 follow-up CM-1279（研究前置 CM-1268）。
4. 三件出貨動作（既有）：PROD 簽章鑰四步（D7）／進版（version-bump）／image 推 Harbor（D12）。
5. ✅ PyMuPDF AGPL 替換（CM-1235）＝出貨合規硬前置，已排棒（2026-08-18）——非決策題，屬待收工程項，列此供 T-4.1 前追蹤。

以上皆為 .4 前置。剩餘未決（2026-08-18 盤點）：第 1 題 AI 功能／第 2 題 Drive OAuth／第 4 題三件出貨動作（第 3 題已收口、第 5 項已排棒）。