C4 容器圖生成器

C4 容器圖生成器 是做什麼的？

遵循 C4 模型規範生成 C4 容器圖，輸出為可編輯的 .drawio XML 檔案，可直接在 draw.io（桌面版或網頁版）中開啟。

使用時機

明確觸發：

• 使用者要求繪製 C4 圖、容器圖或架構圖
• 使用者說「畫出架構」、「系統圖」、「顯示元件」
• 使用者需要將系統架構可視化，用於文件或簡報
• 使用者提到 draw.io、drawio，或想要可編輯的圖表

主動觸發：

• 在解釋一個包含 3 個以上互動元件的系統時
• 在討論微服務、API、資料庫及其關係時
• 在審查或設計系統架構時

跳過時機：

• 使用者想要簡單的流程圖（請改用 Mermaid）
• 使用者想要 UI 線框圖或模型
• 系統元件少於 3 個

流程

步驟 1：收集需求

從對話中識別或詢問使用者：

• 我們要繪製哪個系統？
• 有哪些使用者/參與者（人物）？
• 有哪些容器（應用程式、服務、資料庫、佇列、檔案儲存）？
• 它與哪些外部系統互動？
• 主要的資料流和協定是什麼？

如果使用者提供規格、程式碼庫描述或架構概覽，自動提取元素，並在生成前進行確認。

步驟 2：分類元素

將每個元素對應到 C4 類別：

類別	顏色	形狀	說明
人物	#08427B（深藍色）	shape=actor + 文字標籤	使用者、參與者、角色
容器	#438DD5（藍色）	圓角矩形	應用程式、服務、API
資料庫	#438DD5（藍色）	圓柱體	任何資料儲存（SQL、NoSQL、檔案）
佇列/代理	#438DD5（藍色）	圓角矩形（附標籤）	訊息佇列、事件匯流排
外部系統	#999999（灰色）	圓角矩形	第三方服務、API
系統邊界	無（透明）	虛線矩形	對內部容器進行分組

參考：references/element-templates.md 以取得精確的 draw.io XML 模板。

步驟 3：規劃佈局

採用嚴格的由上而下分層佈局：

第 1 層（y ~= 20）：     人物元素（參與者）
第 2 層（y ~= 250）：    包含內部容器的系統邊界
第 3 層（y ~= 700+）：   外部系統

佈局規則：

• 每個元素都必須有明確的 x, y 座標（不得使用自動佈局）
• 同一層中元素之間至少有 200px 水平間距
• 層與層之間至少有 200px 垂直間距
• 系統邊界 = 包圍所有內部容器的虛線矩形，內邊距為 40px
• 依照主要資料流方向，從左到右排列元素
• 如果系統有不同的子系統，則將相關容器分組到子邊界內
• 保持圖表寬度小於 1600px 以利閱讀
• 在該層內水平居中元素

最小化連線交叉：

• 將經常通訊的元素相鄰放置
• 盡可能垂直佈線
• 避免對角線穿越其他元素
• 禁止箭頭穿過不相關的容器：如果 A 連接到 C，箭頭不得穿過 B。透過以下方式修正：(a) 將 A 和 C 相鄰放置，(b) 使用明確的出口/入口點，或 (c) 重新組織佈局
• 箭頭標籤不得與容器文字重疊：在所有邊上使用 labelBackgroundColor=#ffffff，並使用垂直偏移（mxGeometry 中的 y）將標籤推離容器

步驟 4：定義連線

對於每個連線，指定：

• 來源和目標元素
• 標籤：動作 + 協定（例如「讀寫 [SQL/TCP]」、「發送事件 [AMQP]」）
• 樣式：實線 = 同步呼叫，虛線 = 非同步（事件、佇列、Webhook）
• 方向：始終來源 -> 目標（遵循資料流）

連線規則：

• 每個箭頭都必須有標籤（不得有無標籤的連線）——如果標籤重疊，修正佈局或偏移，切勿移除標籤
• 在所有連線樣式中必須包含 labelBackgroundColor=#ffffff
• 使用 [協定] 後綴：[REST/JSON]、[gRPC]、[SQL]、[AMQP]、[WebSocket]
• 雙向流：使用兩個不同的箭頭，各自帶有明確的標籤
• 自引用：避免（應重新組織圖表）

步驟 5：生成 .drawio XML

以 references/drawio-template.md 中的 XML 結構為基礎。

依照以下規則建構 XML：

1. 從 <mxfile> 包裝器和帶有適當尺寸的 <mxGraphModel> 開始
2. 加入根儲存格（id="0" 和 id="1"）
3. 先加入系統邊界矩形（它們是包含元素的父元素）
4. 加入所有具有明確幾何形狀（x, y, width, height）的元素
5. 加入所有帶有來源/目標參考的連線
6. 在右下角加入圖例

元素尺寸：

• 人物：40 x 60px 參與者 + 下方 220 x 60px 文字標籤
• 容器：240 x 120px
• 資料庫（圓柱體）：240 x 120px
• 外部系統：240 x 120px
• 系統邊界：計算為包圍子元素 + 每邊 40px 內邊距

步驟 6：加入圖例

每個圖表都必須包含圖例。 將其放置在右下角。

圖例必須顯示：

• 人物 = 深藍色火柴人 (#08427B)
• 容器 = 藍色圓角矩形 (#438DD5)
• 資料庫 = 藍色圓柱體 (#438DD5)
• 外部系統 = 灰色圓角矩形 (#999999)
• 實線箭頭 = 同步流
• 虛線箭頭 = 非同步流

參考：references/legend-template.md 以取得精確的 XML。

步驟 7：儲存並驗證

儲存到使用者指定的路徑，或預設為 ./c4_[系統名稱].drawio。

驗證檢查清單：

• 所有元素都有明確的 x, y 座標
• 層級由上而下：人物 -> 系統邊界 -> 外部
• 系統邊界包圍所有內部容器
• 圖例位於右下角
• 無重疊元素（檢查座標 + 尺寸）
• 最少的連線交叉
• 每個連線都有帶協定的標籤
• 實線 = 同步，虛線 = 非同步
• 字型顏色在有色背景上為白色 (#ffffff)
• 檔案可在 draw.io 中正常開啟（有效的 XML 結構）

C4 模型規則

遵循 C4 容器圖限制：

• 容器圖顯示高層次的技術選擇以及容器之間如何通訊
• 每個容器是一個可獨立部署/執行的單元（不是類別或模組）
• 不要混合 C4 層級：此技能僅生成容器層級
• 對於容器內部的元件級細節，請建立單獨的圖表
• 人物元素代表角色，而非個人
• 外部系統是團隊不擁有、系統邊界外的任何事物

反模式

• 禁止自動佈局 - 始終使用明確的 x, y 座標以獲得可預測的結果
• 禁止無標籤箭頭 - 每個連線都需要一個動作和協定
• 禁止缺少圖例 - 每個圖表都必須有圖例
• 禁止擁擠的佈局 - 保持元素之間的最小間距
• 禁止混合 C4 層級 - 僅限容器層級（無類別、無基礎設施）
• 禁止不可見的文字 - 確保字型顏色與背景形成對比
• 禁止硬編碼尺寸 - 從子元素計算系統邊界大小
• 禁止使用 mxgraph.c4.* 形狀 - 它們需要 C4 形狀庫，而 draw.io 預設不會載入。請使用內建形狀：人物使用 shape=actor，資料庫使用 shape=cylinder3
• 禁止箭頭穿過不相關的容器 - 重新安排佈局，使每個箭頭在來源和目標之間都有清晰的路徑
• 禁止標籤不帶 labelBackgroundColor=#ffffff - 裸露的標籤在穿越其他元素時會變得不可讀
• 禁止移除標籤來修正重疊 - 如果標籤與容器重疊，請修正佈局或偏移，切勿移除資訊