lidorshimoni/視覺化

視覺化：架構與流程可視化模式

目的

運用標準 Mermaid 語法，將文字描述的架構、複雜演算法、多智能體互動以及資料模型，轉換成無歧義的視覺圖表。

理論基礎

植根於認知負荷理論與 軟體架構 C4 模型 (Brown, 2018)。視覺模型能將抽象的系統描述具體化，使人類與智能體都能即時驗證系統邊界、資料流與狀態轉換。

標準圖表類型

1. 元件與邊界架構 (C4 容器 / 元件)

使用 flowchart TD 或 flowchart LR 搭配子圖來描繪架構層次：

flowchart TD
    subgraph Client["客戶端層"]
        Web["網頁應用程式 (React)"]
        CLI["命令列工具 (Python)"]
    end

    subgraph Gateway["API 閘道"]
        Proxy["反向代理 / Nginx"]
        Auth["身分驗證服務 (JWT)"]
    end

    subgraph Core["核心服務"]
        App["應用程式引擎"]
        Worker["非同步背景工作器"]
    end

    subgraph Data["持久層"]
        DB[("PostgreSQL")]
        Queue[("Redis 佇列")]
    end

    Web --> Proxy
    CLI --> Proxy
    Proxy --> Auth
    Auth --> App
    App --> Queue
    Queue --> Worker
    Worker --> DB
    App --> DB

2. 請求 / 回應與通訊協定流程 (序列圖)

使用 sequenceDiagram 搭配啟動生命線來顯示時間順序的互動：

sequenceDiagram
    autonumber
    actor 使用者
    participant 智能體 as 程式碼智能體
    participant 工具 as 工具執行器
    participant Git as 版本控制

    使用者->>智能體: 請求實作功能
    智能體->>工具: 執行失敗測試 (紅燈)
    工具-->>智能體: 測試如預期失敗
    智能體->>工具: 編寫最少程式碼 (綠燈)
    智能體->>工具: 執行測試套件
    工具-->>智能體: 所有測試通過
    智能體->>Git: 提交原子性變更
    Git-->>智能體: 生成提交雜湊值
    智能體-->>使用者: 回報任務完成

3. 狀態機與生命週期 (狀態圖)

使用 stateDiagram-v2 表示實體狀態、任務狀態或連線生命週期：

stateDiagram-v2
    [*] --> 草稿
    草稿 --> 審查中: 提交審查
    審查中 --> 已核准: 通過驗證
    審查中 --> 需修改: 發現阻礙
    需修改 --> 審查中: 重新送出修正
    已核准 --> 進行中: 開始實作
    進行中 --> 已完成: 所有測試通過
    已完成 --> [*]

4. 資料模型與關係 (實體關係圖)

使用 erDiagram 表示關聯式架構與領域模型：

erDiagram
    PROJECT ||--o{ SPECIFICATION : contains
    SPECIFICATION ||--o{ TICKET : decomposes_into
    TICKET ||--o{ COMMIT : implemented_by
    TICKET {
        string id PK
        string title
        string status
        string blocked_by
    }

Mermaid 語法安全規則

1. 始終為含特殊字元的節點標籤加上引號：
   • 使用 id["標籤 (額外資訊)"] 而非 id[標籤 (額外資訊)]。
2. 僅使用支援的圖表類型：
   • 流程圖 (flowchart TD)、序列圖 (sequenceDiagram)、狀態圖 (stateDiagram-v2)、類別圖 (classDiagram)、ER 圖 (erDiagram)。
3. 避免在節點文字中使用原始 HTML：請在節點字串內使用純 Markdown 或純文字。

---

引用文獻與來源

1. 軟體架構 C4 模型：Brown, S. (2018). Software Architecture for Developers: Visualise, document and explore your software architecture. Leanpub.
2. Mermaid 圖表標準：Sveidqvist, K., et al. (2014-2026). Mermaid: Markdown-inspired syntax for generating charts and diagrams (https://mermaid.js.org/).
3. 軟體視覺化中的認知負荷理論：Sweller, J. (2011). Cognitive Load Theory. Psychology of Learning and Motivation, Vol. 55.