Mermaid.js 要求圖語法與可追溯性指南

要求圖是一種專用的工程可視化工具，由系統架構師、產品經理和軟體工程師用來繪製技術規格、系統限制和驗證測試。基於 SysML（系統建模語言）標準，原生requirementDiagram引擎可讓您使用基於文字的宣告，直接將抽象的設計要求連結至實際的系統組件和測試案例。

理解要求圖元素

要求圖主要由兩種不同的結構性構建模塊組成：要求方塊（用以指定規則）以及元件方塊（用以模擬程式碼、硬體或測試腳本）。然後在這些方塊之間繪製關係，以建立清晰的可追溯性矩陣。

基本語法結構

每個圖表都以requirementDiagram宣告標頭開始。接下來是使用嵌套屬性定義要求方塊、元件方塊以及方向性關係線。

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
requirementDiagram
  requirement test_req {
    id: 1
    text: "系統必須安全地處理付款。"
    risk: high
    verifymethod: test
  }
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

完整的要求数類分類

並非所有的工程要求都具有相同的重要性。引擎提供六種不同的方塊關鍵字，用以視覺化和語義化地分類您的規格。每種類型都會改變渲染圖形方框內顯示的標題標籤：

  • requirement：標準或一般的系統規格。
  • functionalRequirement：指定系統必須執行的動作或行為能力。
  • interfaceRequirement：定義組件之間的連接點、資料交換或通訊協定。
  • performanceRequirement：設定可量化的執行指標，例如速度、可擴展性、吞吐量或容量。
  • physicalRequirement：規定材料限制、尺寸、重量或硬體限制。
  • 設計約束: 限制軟體選擇、架構風格、框架或合規標準。
Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
需求圖表
  設計約束 遺留約束 {
    id: "CON-04"
    text: "後端必須維持與 PHP 8.2 流水線的向後相容性。"
    risk: low
    verifymethod: inspection
  }
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

語法參考：需求元素與修飾符

下表將需求解析器原生識別的主要語義關鍵字、必要屬性與分類結構進行分解。

語法元件 需求類型 描述與支援的系統屬性
宣告 關鍵字識別符 初始化 SysML 需求工作區畫布。必須使用精確的 需求圖表 程式區塊標題。
唯一識別碼屬性 id: 字串 / 整數 一個強制性的嵌套參數，用於提供追蹤索引或在您的追蹤框架內的唯一字母數字參考代碼。允許混合空格。
文字屬性 text: 引號內的字串 一個強制性的描述性字串，用以詳細說明項目實際的規格或行為約束。必須始終用雙引號包圍。
風險屬性 risk: 嚴重程度標記 一個可選的標記，用於追蹤架構風險的嚴重程度。接受低階標記：low, 中等，或高.
驗證屬性 驗證方法：方法標籤 一個可選參數，用於聲明規則將如何被證明。接受標準工程值：分析, 示範, 檢驗，或測試.
系統元件 元件模組 使用語法聲明一個實體元件、軟體元件或測試腳本：元件 元件名稱 { 類型："元件類型" }.

進階關係與可追溯性連結

需求圖的主要功能在於將需求與實際系統相連。連結使用專用的、帶類型的箭頭連接器繪製（例如，- 滿足 ->）以建立明確的結構意圖。

支援的關係運算子

關係語法標記 戰略工程意義 方向性流動規則
來源 - 包含 -> 目標 將一個廣泛的父級需求分解為較小的、嵌套的子需求。 從父級需求方塊指向子需求方塊。
元件 - 滿足 -> 需求 證明一個實際的軟體或硬體元件成功符合某項規則。 從 元件方塊指向目標需求方塊。
元件 - 驗證 -> 需求 表示特定的測試腳本或測試案例用來檢查規則的正確性。 從測試元件方塊指向目標需求方塊。
來源 - 複製 -> 目標 表示一個與其他位置的主需求完全對應的重複需求。 從重複副本指向主原始方塊。
來源 - 跟蹤 -> 目標 在兩個獨立的需求之間建立廣泛的依賴關係或歷史關係。 從依賴的需求指向主要目標方塊。
來源 - 派生 -> 目標 表示某項需求是直接由另一項需求計算或產生的結果。 從派生的子方塊指向來源父方塊。
來源 - 精細化 -> 目標 為高度複雜的高階技術規格增加額外的細節或清晰度。 從精細化的規格指向基準目標方塊。

使用者定義的元件與擴展屬性

除了標準要求之外，還包括element關鍵字可讓您將特定應用程式指令碼、硬體項目或第三方套件對應至您的追蹤路徑。每個 element 區塊可透過使用其大括號內的type:模式來儲存自訂的鍵值資料元屬性。

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
requirementDiagram
  element payment_gateway_api {
    type: "Stripe 微服務模組"
  }
  
  element compliance_audit_log {
    type: "不可變資料庫表格"
  }
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

現實世界藍圖：複雜的電子商務安全基礎架構

此全面的藍圖追蹤完整的生產合規生態系統。它透過contains展示分解，標示效能限制，透過satisfies連結軟體模組，並使用verifies迴圈來標示整合測試案例。

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
requirementDiagram
  
  %% 要求層級層
  requirement security_master_req {
    id: "SEC-001"
    text: "應用程式平台必須維持嚴格的 PCI-DSS 標準合規性。"
    risk: high
    verifymethod: test
  }

  performanceRequirement checkout_speed_req {
    id: "PERF-22"
    text: "MFA 加密驗證握手必須在 200 毫秒內完成編譯。"
    risk: medium
    verifymethod: analysis
  }

  interfaceRequirement secure_token_req {
    id: "INT-09"
    text: "API 資料傳輸必須使用加密的 JSON Web Token (JWT)。"
    risk: high
    verifymethod: test
  }

  %% 系統元件層
  element auth_service_code {
    type: "Go 後端微服務"
  }

  element load_tester_script {
    type: "K6 性能指令碼"
  }

  element jwt_validator_test {
    type: "Jest 整合單元測試套件"
  }

  %% 架構關係路徑
  security_master_req - contains -> checkout_speed_req
  security_master_req - contains -> secure_token_req
  
  auth_service_code - satisfies -> secure_token_req
  load_tester_script - verifies -> checkout_speed_req
  jwt_validator_test - verifies -> secure_token_req
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

常見語法陷阱與系統限制

在編譯精確的工程地圖時，請記住這些驗證參數，以避免解析錯誤：

  • 字串必須使用雙引號：文字區塊和類型（例如，text: "描述", type: "元件"）*必須*以雙引號包覆。使用單引號或未加引號的字串將導致編譯器中斷。
  • 嚴格的屬性語法： 括號內的屬性必須使用冒號直接跟隨值（例如，id: 1）。遺忘冒號或在沒有適當縮進間距的情況下將其寫在同一行，可能會導致錯誤。
  • 有限的值選擇： 這risk 和 verifymethod 參數僅接受明確的系統標記（例如，low, medium, high 表示 risk；analysis, demonstration, inspection, test 表示 verifymethod）。輸入自定義值如risk: extreme 將導致佈局建構器失效。
  • 箭頭間距完整性： 方向線必須在運算符周圍使用空格間距輸入（例如，A - satisfies -> B）。將字串緊湊為A-satisfies->B 將丟棄系統處理例外情況。
返回頂端