用於資料庫關係的 Mermaid ER 圖

實體關係圖用於表達資料結構和基數。它可以幫助 schema 設計和新人上手，但不能取代可執行的 migration。應把它看作對重要約束的說明，而把資料庫定義視為最後事實來源。

建模實體和屬性

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_ITEM : contains
  PRODUCT ||--o{ ORDER_ITEM : appears_in

  CUSTOMER {
    uuid id PK
    string email UK
    datetime created_at
  }
  ORDER {
    uuid id PK
    uuid customer_id FK
    string status
  }
  ORDER_ITEM {
    uuid order_id FK
    uuid product_id FK
    int quantity
  }
  PRODUCT {
    uuid id PK
    string name
    decimal price
  }

ER 圖裡的屬性型別只是描述性的。可以使用團隊習慣的詞彙，但不要以為圖能強制資料庫特定的精度、索引、預設值或檢查約束。

從兩端讀取基數

CUSTOMER ||--o{ ORDER 表示每個訂單都屬於且只屬於一個客戶，而一個客戶可以有零個或多個訂單。把兩端都讀清楚，才能避免「客戶有訂單」這種模糊說法掩蓋可選性。

關係標籤可以用 places 或 contains 這種更自然的動詞。標籤是文件，不是外鍵名。

只展示需要的 schema

完整的 production 資料庫通常還會包含稽核欄位、技術索引、整合欄位和連接表，過多細節會把總覽淹沒。應該先做一張領域級 ER 圖，只保留理解關係所需的鍵和屬性；更詳細的內容再連到 migration 或生成的 schema 文件。

如果是 schema 變更的 Pull Request，只有概念模型變化時才更新圖。新增一個可為空的 telemetry 欄位，通常不屬於總覽；新增一個所有權關係，通常就應該更新。

用資料庫驗證假設

確認可選性、唯一性和關係方向是否真的和約束一致。圖裡寫「必須唯一」但外鍵實際可空，會造成誤導。逆向梳理舊 schema 時，如果某個關係不確定，應該在正文裡標註，而不是把猜測寫成強約束。

可以在 Mermaid 編輯器 裡用 ER 模板驗證語法，並匯出可縮放的 SVG 作為架構文件。