SDD-000　設計總覽與通用規範

1. 本文件之定位

SDD-001 ~ SDD-007 定義本系統之細部設計。本文件定義跨設計文件之共通規範：
分層職責、命名、通用模式、交易邊界、錯誤處理與擴充機制。
任一設計文件與本文件衝突者，以本文件為準。

2. 分層職責

2.1 各層產出物對照

3. 命名規範

4. 通用設計模式

4.1 交易邊界（Unit of Work）

原則：一個用例 = 一個交易邊界 = 一個聚合的異動。

flowchart TD
  A["用例開始"] --> B["開啟交易"]
  B --> C["載入聚合"]
  C --> D["執行領域行為"]
  D --> E["驗證不變式"]
  E --> F["持久化聚合"]
  F --> G["寫入 Outbox 事件"]
  G --> H["提交交易"]
  H --> I["交易後發布事件"]
  E -->|"不變式違反"| X["回滾並回報錯誤"]
  F -->|"樂觀鎖衝突"| X
  G --> X

規則

4.2 冪等（Idempotency）

flowchart TD
  A["寫入請求"] --> B{"是否帶冪等鍵"}
  B -->|"否"| E["拒絕：400 缺少冪等鍵"]
  B -->|"是"| C{"冪等鍵是否已存在"}
  C -->|"是，且請求指紋相同"| D["回傳前次結果（200／201）"]
  C -->|"是，但指紋不同"| F["拒絕：409 冪等鍵衝突"]
  C -->|"否"| G["執行業務邏輯"]
  G --> H["寫入結果與冪等鍵（同一交易）"]
  H --> I["回傳結果"]

4.3 樂觀鎖（Optimistic Locking）

4.4 Outbox（可靠事件發布）

4.5 補償（Saga）

詳見 SDD-004 §4。

4.6 規格模式（Specification）

複雜業務條件（如授權檢核 13 大項）以規格物件組合，不得以 if-else 硬寫。

4.7 領域事件

5. 錯誤處理原則

5.1 例外階層

classDiagram
  class DomainError {
    +string code
    +string message
  }
  class ValidationError
  class BusinessRuleError
  class ConcurrencyConflictError
  class IdempotencyConflictError
  class StateTransitionError
  class ResourceNotFoundError
  class ExternalSystemError
  class InfrastructureError
  DomainError <|-- ValidationError
  DomainError <|-- BusinessRuleError
  DomainError <|-- ConcurrencyConflictError
  DomainError <|-- IdempotencyConflictError
  DomainError <|-- StateTransitionError
  DomainError <|-- ResourceNotFoundError
  DomainError <|-- ExternalSystemError
  DomainError <|-- InfrastructureError

6. 擴充機制（客製化與自主開發）

對應 BRD-001 之客製化需求與 SYS-5／SYS-6。

規則：擴充機制不得以修改核心程式碼為手段；核心程式碼不得含個別客戶之特例分支。

7. 設計文件之檢核