UML 使用案例圖（UML Use Case Diagram）

關於使用案例圖

使用案例圖回答了每次需求參與都從此開始的問題：這個系統做什麼，為誰做？ 由 Ivar Jacobson 於 1992 年提出，並納入 UML 2.5.1 §18，它是最常被教授的 UML 圖，也是產品、工程與 QA 之間的共通語言。符號很精簡——參與者火柴人、使用案例橢圓、系統邊界，以及四種線型——但它能比任何方框箭頭的流程圖更清楚地固定系統範圍。

Schematex 以單一關鍵字 usecase 與專為 LLM 生成設計的文字 DSL 實作了 UML 2.5.1 視覺子集——PlantUML 的開發體驗，不需要 JVM 也不需要繁複的括號操作。與 state（物件內部行為，而非系統範圍）、flowchart（無參與者／主題／include-extend 語義）和 bpmn（流程如何執行，而非系統提供什麼）不同。

usecase·§ —

↘ preview

100%

UTF-8 · LF · 17 lines · 303 chars✓ parsed·13.3 ms·4.6 KB SVG

1. 第一個使用案例圖

每份文件以 usecase 關鍵字開頭，然後是標題屬性、宣告與關係：

usecase
system: "Library"

actor: Member
usecase: "Borrow Book" as Borrow

Member -- Borrow

actor: 宣告一個參與者（火柴人），usecase: 宣告一個使用案例（橢圓），Member -- Borrow 在它們之間繪製一個純關聯。system: 將使用案例包裹在一個帶標籤的主題矩形中。主要參與者放在左側；支援參與者放在右側。

標題接受以下屬性：

title: "…" — 繪製於圖表上方的標題。
system: "…" — 主題（系統邊界）名稱。省略它可讓使用案例自由浮動（若省略且有 ≥3 個使用案例，Schematex 會發出警告）。
direction: LR | TB — 預設 LR（參與者從兩側夾住主題）。
generalization: tree | individual — 是否合併同級泛化箭頭（預設 tree）。

2. 參與者

actor: Customer
actor: "Payment Gateway" as PG (external)
actor: "Warehouse Staff" as WH
actor: Admin (left)

裸名稱或 "引號" 名稱成為標籤；as ID 給予短識別符用於關係。
(external)（或 (system)）將參與者渲染為帶有 «actor» 原型的矩形，而非火柴人——用於其他軟體系統（支付閘道、第三方 API）。
(business) 在火柴人上加上 Bittner & Spence 的對角斜線。
(left) / (right) 將參與者固定在某一側。預設第一個參與者在左側，其餘在右側。

自訂原型放在宣告後的書名號中：actor: "Audit Service" as Audit (external) «system»。剖析器也接受 ASCII 的 <<system>> 並標準化為 «system»。

3. 使用案例

usecase: "Checkout" as Checkout {
  extension point: payment failed
  extension point: stock depleted
}

使用案例是一個大小配合文字的橢圓。可選的 { … } 區塊在名稱下方以分隔線隔出擴充點區隔。這裡也支援原型：usecase: "Validate Card" as ValidateCard «secured»。

4. 關係

四種線型連接參與者與使用案例：

DSL	含義	渲染方式
`A -- B`	關聯	實線，無箭頭
`A --> B`	有向關聯	實線，B 端開箭頭
`A ..> B`	`A` 包含 `B`	虛線，開箭頭 → B，`«include»` 標籤
`A <.. B`	`A` 擴充 `B`	虛線，開箭頭 → B（基礎），`«extend»` 標籤
`A --\|> B`	`A` 是 `B` 的特化	實線，空心三角形 → 父類別 B

Customer -- Checkout
Checkout ..> Pay          : «include»
Pay      ..> ValidateCard : «include»
Cancel   <.. Checkout     : «extend» [payment failed] (extension point: payment failed)

«include» 指向被包含的使用案例——可重用的行為 A 總是執行。來源包含目標。
«extend» 指向基礎使用案例——A 是可選行為，B 是它所擴充的基礎。你可以附加一個 [condition] 並參考基礎的某個 (extension point: …) 項目。（箭頭始終朝向基礎，不管端點的排列順序。）
«extend» 線以主題強調色繪製，使這個較少見、較令人意外的關係更加顯眼。

剖析器會拒絕人類與 LLM 都常犯的高信心錯誤，並附上錯誤行號：兩個參與者之間的關聯、兩個使用案例之間的關聯、include／extend 觸及參與者、跨元類別的泛化（參與者 → 使用案例）、重複使用的識別符，以及引用不存在於基礎使用案例上的擴充點。

5. 泛化

--|> 在兩個參與者或兩個使用案例之間有效（絕不能跨兩者——這是硬性錯誤）：

actor: User as U
actor: "Premium User" as PU
PU --|> U

usecase: "Pay by Card"   as PayCard
usecase: "Pay by PayPal" as PayPaypal
usecase: "Pay"           as Pay
PayCard   --|> Pay
PayPaypal --|> Pay

箭頭帶有空心三角形指向父類別。當三個以上的同級共享一個父類別時，箭頭合併為單一共享箭頭（UML 2.5 圖 18.5 慣例）；在標題中設定 generalization: individual 可保持它們分開。參與者層次結構在參與者堆疊外側路由為整潔的匯流排。

6. 多重性

在它所屬的端點旁邊直接引號多重性字串：

Customer "1"    -- "*" Checkout
Cashier  "1..*" -- "1" Register

7. PlantUML 風格的行內形式

從 PlantUML 遷移過來？行內宣告形式有效，且可與宣告式形式自由混用：

usecase
:Customer: as C
(Browse Catalog) as Browse
(Add to Cart)    as AddCart

C -- Browse
C -- AddCart
Browse ..> AddCart : «include»

:Name: 宣告參與者，(Name) 宣告使用案例，as ID 為兩者設定別名。Schematex 是受 PlantUML 啟發，並非 1:1 的轉譯器——多重性與關係語法略有不同。

8. 語法（EBNF）

document     = "usecase" NEWLINE header_prop* statement*
header_prop  = ("title:" | "system:") quoted_string
             | "direction:" ("LR" | "TB")
             | "generalization:" ("tree" | "individual")

statement    = actor_decl | usecase_decl | plantuml_inline | relation | note

actor_decl   = "actor" ":" name ("as" IDENT)? actor_kind? stereotype?
actor_kind   = "(" ("external" | "system" | "business" | "left" | "right") ")"
usecase_decl = "usecase" ":" quoted ("as" IDENT)? stereotype? extpoints?
extpoints    = "{" ("extension point:" TEXT)+ "}"
plantuml_inline = ":" name ":" ("as" IDENT)?      ; actor
                | "(" name ")" ("as" IDENT)?       ; use case

relation     = endpoint relop endpoint label_clause?
endpoint     = (IDENT | quoted) multiplicity? | multiplicity? (IDENT | quoted)
relop        = "--" | "-->" | "..>" | "<.." | "--|>"
label_clause = ":" stereotype? condition? extpoint_ref?
stereotype   = "«" TEXT "»" | "<<" TEXT ">>"
condition    = "[" TEXT "]"
extpoint_ref = "(extension point:" TEXT ")"
multiplicity = quoted_string                       ; "1", "*", "0..1", "1..*"

Schematex 遵循 OMG **UML 2.5.1 §18（UseCases）**視覺子集與 Bittner & Spence 風格指南：渲染的 SVG 使用書名號（而非 ASCII 的 <<>>），«include» 指向被包含的使用案例，«extend» 指向基礎，空心三角形泛化箭頭，以及外部系統矩形上的 «actor» 原型。文字使用案例描述（Cockburn 完整形式）、情境表格與 XMI 匯出超出圖表渲染器的範疇。完整規格見 docs/reference/29-USECASE-STANDARD.md。