Entity Derivation

澄清模式（Feature Files + API Spec 完成後）

1. 掃描所有 Feature File。 蒐集出現在 Given datatable、When 參數、Then 驗證表格中的所有實體與屬性。
2. 與現有草稿合併。 將 Feature File 中發現的屬性與 ES Aggregates 映射的初版交叉比對，補充型別、約束、列舉定義。
3. 識別列舉型別。 將 Feature File 中出現的有限值集合（狀態、類型、方法等）提取為 Enum 定義，並將對應欄位型別設為該 Enum。
4. 僅澄清仍不明確的部分：
   • 從上下文無法判斷的屬性型別
   • Feature Rule 中尚未表達的約束（如 price > 0）
   • 實體間的關聯（一對一、一對多、多對多）
5. 每次澄清後更新 erm.dbml，展示更新內容，與用戶確認。

澄清規則

• 依照協調器定義的澄清循環進行。
• 不詢問 Feature File 中已明確的屬性。 若 datatable 中出現 | price | 50 |，屬性名稱與型別（int）已顯而易見。
• 澄清重點聚焦於：模糊的型別、缺少的約束、實體間的關聯。

DBML 格式

Enum 定義

當屬性的值域為有限集合（如狀態、類型、方法），必須定義為 Enum，不可用 varchar + note 列舉替代。

Enum <enum_name> {
  VALUE_A [note: '<中文說明>']
  VALUE_B [note: '<中文說明>']
}

• Enum 名稱使用 snake_case，與其所描述的概念對應（如 order_status、coupon_type）。
• 每個 Enum 值附帶 [note: '...'] 提供中文對照。

Table 定義

// <實體說明>
Table <table_name> {
  <field_name> <type> [<attributes>]

  indexes {
    <field_name>
    (<field1>, <field2>) [unique]
  }

  Note: '''
  <實體用途>

  <僅保留 DBML 語法無法表達的約束>：
  - <跨屬性不變條件>
  - <狀態流轉規則>
  - <嵌套結構（如 JSON）的 schema 說明>
  '''
}

欄位屬性（Column Attributes）

以 [attr1, attr2, ...] 語法組合：

欄位型別

Enum vs Note 判定原則

原則：能用 DBML 結構（Enum、ref、index、attribute）表達的，就不放在 Note 裡。

推導規則

• 實體清單以 ES Aggregates 為權威來源。 若 ${ES_SPEC_PATH} 中定義了 Aggregates，每個 Aggregate 直接對應一個 Table，不遺漏、不合併、不拆分。
• 每個屬性必須可追溯至 ES Aggregate 屬性表或 Feature File。 優先採用 ES Aggregate 的屬性定義，再以 Feature File 的 datatable 補充細節。
• 實體名稱來自 ES Aggregate 名稱（若存在），否則來自 Feature File 中使用的術語。
• 列舉型別由 Feature File 中出現的有限值集合推導（如 datatable 中出現 | status | CREATED |、| status | PAID |，則推導出 Enum order_status { CREATED; PAID; ... }）。
• 約束來自前置條件規則（如「前置（參數）- 數量必須大於 0」對應 quantity > 0 約束）。
• 關聯由實體在情境中的共現方式推導（如 CartItem 同時引用 Cart 與 Product）。

核心約束

僅將 Feature File 中包含的內容形式化，不添加推測性的屬性或實體。

完成條件

當所有實體皆已定義完成並經用戶確認，輸出完整的 ${ENTITY_SPECS_DIR}/erm.dbml。