【2026 最新】Archify Architecture Delta 教學：可驗證 Before／Delta／After SVG

架構圖最危險的時刻，不是畫得醜，而是畫得很有說服力，卻沒有忠實反映改版。如果 Reviewer 只看到一張 After 圖，很難知道哪個節點真的新增、哪條路徑只是換位置、哪個 Label 被悄悄改寫。這篇 Archify Architecture Delta 教學，會把架構改版拆成固定的 Before、固定的 After、可失敗的 Delta 收據，再輸出可審查的 SVG。

本文用 Archify v2.15.0與英國司法部公開的 Digital Canteen Medusa Repo實作：比較 Redis 還是註解腳手架、以及 Redis 已接上 cache／workflow 的相鄰 commit。成品包含三聯圖、兩份 Typed JSON IR、收據與三種故障注入。

先說結論：可信的改版圖至少要有四件事

• 兩端固定：Before 與 After 都要綁公開 Repo、完整 40 字元 commit SHA，以及存在於該版本的 source path。
• 穩定 ID：同一個服務跨版本沿用同一個 id；否則重新命名會被誤判成刪除再新增。
• 會失敗的 Gate：Schema、Layout、Route 出錯時必須回傳非零退出碼與可定位診斷，不能只靠肉眼覺得「大概沒事」。
• 人機雙重證據：Before／Delta／After 給人閱讀，Receipt JSON 給 CI 或審查腳本核對；最後仍要在瀏覽器做人工複核。

最小可信單位＝固定 Before ＋ 固定 After ＋ 可失敗 Delta 收據；少一項，就只是一張說服人的圖。

Archify Architecture Delta 是什麼？

Archify不是拖拉式繪圖器。Agent 先整理 Typed JSON IR（此處是受 JSON Schema 約束，不是 TypeScript 靜態型別），Archify 再校驗並編譯成含 inline SVG 的單檔 HTML。Architecture Delta 自 v2.13.0加入：驗證兩份 IR、用穩定 ID 配對，輸出三聯圖與 .receipt.json。

邊界要先講清楚：Delta 比較的是作者寫進 IR 的事實，不推斷 runtime impact、因果、風險或能否合併；source evidence 只驗證 commit、path 與行號存在，不自動證明語意支持節點。「Redis 被加到圖上」不等於 production 健康或 PR 可以 merge。

步驟一：固定 Archify 與目標 Repo 版本

截至 2026 年 8 月 30 日，最新穩定版是 v2.15.0，需 Node.js 18 以上。不要只寫「最新版」；同一份 IR 日後可能遇到不同 Validator 規則。

git clone --branch v2.15.0 --depth 1 \
  https://github.com/tt-a1i/archify.git /tmp/archify-v215

cd /tmp/archify-v215/archify
git rev-parse HEAD
# e1ac748f19cf805e44bf74fb93c796662152e273

node bin/archify.mjs doctor

這個 MIT 授權 Repo 的 PR #14於 2026 年 6 月 12 日合併；base d86d5ec…與 squash commit f770be6…是 Git 可核對的父子版本。

git clone \
  https://github.com/ministryofjustice/hmpps-digital-canteen-medusa-service.git \
  /tmp/digital-canteen

git -C /tmp/digital-canteen cat-file -e \
  d86d5ec74a940a5c3023a123e1ed668a26975324^{commit}
git -C /tmp/digital-canteen cat-file -e \
  f770be6d41bfac859ca622efa1a91c631ef76b9b^{commit}

只建模有直接證據的 Medusa Backend、PostgreSQL、Redis 與兩條連線；沒有證據的 region、security group、流量與健康度不畫。「小而可證」比塞滿整個 Repo 更適合 Review。大型改版可先用 大型 Repo 安全改版流程盤點範圍。

步驟二：把 Before／After 寫成 source-backed Typed IR

Before 與 After 各是一份 architecture.json。meta.repository.revision固定版本，sources指出事實所在檔案與行號；正式檔案還要填入節點位置、大小與關係。

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Digital Canteen Medusa",
    "quality_profile": "showcase",
    "repository": {
      "url": "https://github.com/ministryofjustice/hmpps-digital-canteen-medusa-service",
      "revision": "f770be6d41bfac859ca622efa1a91c631ef76b9b"
    }
  },
  "components": [{
    "id": "redis",
    "type": "database",
    "label": "Redis",
    "sublabel": "cache + workflow engine",
    "sources": [
      {"path": "docker-compose.yml", "line": 12, "end_line": 15},
      {"path": "backend/medusa-config.js", "line": 85, "end_line": 98}
    ]
  }]
}

Base 的 Redis 仍是註解腳手架；Head 的 redis:7已啟用，設定也加入 cache／workflow 模組。PostgreSQL 與 backend-postgres ID 不變；After 只新增 redis與 backend-redis。

Label 不是裝飾。同一個 Redis 若只是多承擔 workflow，應保留 id: redis並修改 sublabel；不要拆成兩個沒有原始碼依據的服務。

步驟三：用 Archify Architecture Delta 產生收據

ARCHIFY=/tmp/archify-v215/archify
REPO=/tmp/digital-canteen

node "$ARCHIFY/bin/archify.mjs" validate architecture base.architecture.json \
  --quality showcase --repo-root "$REPO" --json > base.validate.json

node "$ARCHIFY/bin/archify.mjs" validate architecture head.architecture.json \
  --quality showcase --repo-root "$REPO" --json > head.validate.json

node "$ARCHIFY/bin/archify.mjs" compare architecture \
  base.architecture.json head.architecture.json digital-canteen-delta.html \
  --quality showcase --repo-root "$REPO" --json > compare.stdout.json

三個命令都須退出碼 0。本文的 Archify Architecture Delta 實跑為 revision-pinned、complete、28／28 checks，兩端 composition 都 pass：新增 Redis、變更 Medusa Backend 語意、新增 backend→Redis；presentation 不變，provenance 改變。

Review 頁籤可逐項看 authored change；receipt 保存兩端 raw／semantic SHA-256、commit 與分類。HTML、receipt 和兩份 IR 要一起放進 PR artifact，日後才能重跑。

步驟四：故障注入，驗證 Schema／Layout／Route Gate

只跑正確輸入，不能證明 Gate 會擋錯。複製 head IR 三次，每次只破壞一項，並期待 validate非零；不要同時製造多個故障。

1. Schema：在根物件加入 "invented_field": true。實跑由 schema/additionalProperties擋下。
2. Layout：把 Redis 的 pos改成與 PostgreSQL 完全相同。實跑回報 layout/constraint，並同時指出 edge-through-node 與 label-route-clearance 問題。
3. Route：刪掉 Redis component，卻保留 backend-redis關係。實跑由 layout/constraint指出未知 target redis。

修復時讀 subject、evidence與 supportedFixes，只改被點名處。這種 fail-closed 思維也可延伸到 Claude Code Hooks 三道閘門；固定輸入與評分則可參考 Steerability 回歸測試。

步驟五：瀏覽器複核與 SVG／PNG 交付

Gate 通過後仍要打開 HTML，切換三個視圖，檢查 Label、箭頭、遮擋、主題與 Review 項目。Export 可下載 SVG、PNG／Share Card；基本交付可先讀 Diagram Design 教學。

node "$ARCHIFY/bin/archify.mjs" deliver architecture head.architecture.json \
  head.html --quality showcase --repo-root "$REPO" --json \
  > head.deliver.json

node "$ARCHIFY/bin/archify.mjs" visual-check head.html --json \
  > head.visual-check.json

Standalone Before／After 在四個桌面 viewport 都通過 containment；但 v2.15.0 compare viewer 回報垂直 overflow，退出碼 1。所以這次不能稱為「全部視覺 Gate 通過」；保留收據與人工檢查，並把 containment 列為待修。漂亮截圖不能覆蓋失敗退出碼。

本文固定的 v2.15.0 Schema 尚無 meta.locale，所以 IR 不填這個欄位，Viewer 固定介面維持英文。en／zh-CN是目前 2.16.0-dev.0主線的未發布行為，不應混進穩定版指令。

靜態 SVG 還要確認：README 寬度可讀、箭頭明確、差異不只靠顏色、原始碼連結固定到 commit。CI 應查 receipt 與退出碼，不要用「像素完全相同」判分。

Mermaid baseline：什麼時候反而比較適合？

Mermaid CLI可把 .mmd輸出成 SVG、PNG、PDF，適合 README、Issue 與未定案拓撲。Archify 要先建 IR、穩定 ID、位置與 evidence；只想快速說清楚時，這筆成本未必划算。

本文的 Mermaid baseline 只驗官方 CLI 的 .mmd轉 SVG／PNG／PDF；沒有替它外掛 revision evidence、stable-ID Delta 或收據層。若你的 Mermaid 流程已有這些外部 Gate，應把它們一起納入比較。可讀性沒有自動冠軍；必須用同一拓撲、問題與尺寸比較。本文也不把 Archify 官方未填的 Mermaid 實驗評分表當證據。

可以直接放進 PR 的驗收清單

• 工具版本、Before SHA、After SHA 都已固定，且不是 branch 名稱。
• 每個重要節點都有可核對的 source path；沒有證據的邊界不畫。
• 相同元件沿用穩定 ID；Label、角色與路徑的改動有明確理由。
• base/head validate、compare 退出碼與 receipt 已保存。
• Schema、Layout、Route 各有一個獨立故障注入，且都如預期失敗。
• Before／Delta／After 已人工檢查；任何 visual-check 非零結果都列為 blocker 或已知限制。
• PR 同時附 HTML、receipt、兩份 IR 與靜態 SVG／PNG，不只貼一張圖。

常見問題 FAQ

1. Archify 能直接掃 Repo 自動保證架構正確嗎？

不能。Agent 或作者先建立 IR；Archify 可以驗證指定 source path 在固定 commit 中存在，但不會自動證明你漏掉的服務、線上流量或因果關係。

2. 為什麼一定要完整 40 字元 SHA？

完整 SHA 能把證據固定到唯一 Git object，避免 branch 漂移與短 SHA 歧義；Archify 的 repository evidence Schema 也要求完整 commit。

3. 重新命名節點時要換 ID 嗎？

如果仍是同一個架構物件，通常保留 ID、修改 label 或 sublabel；只有物件身份真的改變，才應換 ID。否則 Delta 會把重新命名誤讀成刪除與新增。

4. Compare 通過就代表可以 merge 嗎？

不代表。收據明確限制為 authored IR 差異，不推斷 runtime impact、風險、因果或 mergeability；測試、資安、效能與部署審查仍要分開完成。

5. 為什麼還要故障注入？

因為「正確輸入能成功」只驗到 happy path；故障注入才會證明未知欄位、重疊節點與懸空連線真的能被 Gate 擋下。

6. Archify 可以輸出純 SVG 嗎？

可以從 Viewer 的 Export 選單下載 SVG；主要交付仍建議保留含互動與證據的單檔 HTML，以及旁邊的 receipt JSON。

7. Mermaid 可以取代這套流程嗎？

Mermaid 很適合快速、文字化的單一狀態圖，也能輸出 SVG／PNG／PDF；若需要 revision-pinned source evidence、穩定 ID Delta 與機器收據，則要自行補上相同的驗收層。

8. visual-check 失敗但肉眼正常，可以忽略嗎？

不應把它寫成通過。先保存失敗 viewport 與截圖，判斷是圖面、Viewer chrome 或工具限制；修正或明列 blocker。人工複核能補充證據，不能把非零退出碼改寫成成功。

結論：把架構圖從說明素材升級成驗收證據

Archify Architecture Delta 的價值不是把新增節點塗綠，而是強迫作者交代版本、身份、證據、失敗條件與審查者。這個小型 Redis 案例仍完整走過父子 commit、source evidence、28／28 比較、三種預期失敗，以及未被粉飾的 visual-check blocker。

請記住本文的錨點：固定 Before ＋ 固定 After ＋ 可失敗 Delta 收據。下一次 PR 不要先問圖漂不漂亮；先拿掉一個節點、一路徑或一個欄位，看看流程會不會真的拒絕它。會拒絕錯誤的圖，才開始有資格成為 Review 證據。