Component Design · 元件設計

---
doc_type: "component-design"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["module-design", "api-spec"]
  optional: ["class-diagram", "adr"]
---

# Component Design: <module-name>

**Status:** Draft · **Owner:** <SD> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 5 段（編號 1, 2, 3, 9, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每結論行內加 `（依據：module-design §XXX / api-spec §YYY）`；每欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造元件或介面。**核心紀律：依賴指向內層 (domain)，adapter 可替換**——元件圖的依賴箭頭只准朝內，任何 domain → infra 的箭頭即不合格。介面契約須含 provided + required interface，只寫方法名不寫錯誤行為不接受。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行說明本模組含哪些元件、哪些是 domain port、哪些是 infra adapter、最高風險 -->

<3-5 行說明>

> **TL;DR:** <一句話：元件數 + 哪些 port 可替換 + 依賴方向>

---

## 2. Component Diagram

<!-- ai-rule: Mermaid 無原生 UML component 型別，用 flowchart 配 «interface» 標籤表達 provided/required interface；依賴箭頭只准朝內 (domain)。標出哪些是 port (interface)、哪些是 adapter (impl) -->

```mermaid
flowchart LR
    subgraph domain["Domain（內層）"]
        SVC["OrderService<br/>«component»"]
        PORT["«interface»<br/>OrderRepository<br/>(port)"]
    end
    subgraph infra["Infra（外層 · adapter 可替換）"]
        ADP["PgOrderRepository<br/>«adapter»"]
    end
    API["Order API<br/>«component»"] -->|requires| SVC
    SVC -->|requires| PORT
    ADP -.implements.-> PORT
    ADP -->|uses| DB[("Postgres")]
```

> 依賴方向：`API → Service → «OrderRepository» port`，adapter `PgOrderRepository` 由外層 implements port（箭頭朝內），換 DB 只換 adapter。

---

## 3. Interface Contracts

<!-- ai-rule: 每個元件列 provided interface（對外提供）+ required interface（向內依賴的 port）。只寫方法名不寫回傳/錯誤行為不接受 -->

| Component | Provided interface | Required interface (port) | Confidence |
|---|---|---|---|
| Order API | `POST createOrder(dto) → 201 \| 409` | `OrderService` | **[H]** |
| OrderService | `place(cmd) → Order \| DomainError` | `OrderRepository` | **[H]** |
| PgOrderRepository | implements `OrderRepository` | `Postgres pool` | **[M]** |

- `OrderRepository.save(order) → void \| ConflictError`：唯一鍵衝突回 `ConflictError`，不洩漏 `sql.Error`（依據：module-design §repo）

---

## 9. Risks

<!-- ai-rule: 至少 3 個（leaky abstraction / hidden temporal coupling / circular DI），每條含失效模式 + Mitigation + Owner -->

> **R1:** <e.g. `OrderRepository.find` 回傳 `sql.Rows`（leaky abstraction），domain 被 driver 綁死> — **Mitigation:** port 只回 domain 型別 — **Owner:** <SD>
>
> **R2:** <e.g. Service 假設 Repository 已先呼叫 `init()`（hidden temporal coupling）> — **Mitigation:** 建構子注入完成即可用 — **Owner:** <Dev Lead>
>
> **R3:** ...

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions（推測但 input 未明說）：**
  - <假設 1：例：假設 OrderRepository 用 Postgres adapter（module-design 未指定）>
- **Highest-value next input:** <下一份最該補的：class-diagram（元件內部結構）/ ADR（持久化選型）>

### TODO（缺資料）

- _TODO: 需要 Dev Lead 確認 OrderRepository port 是否需支援 batch save_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 5 段 H2 章節齊全（編號 1, 2, 3, 9, 12，刻意不連號）
> - [ ] Component Diagram 含 mermaid，標出 port (interface) vs adapter (impl)
> - [ ] 依賴箭頭只朝內（無 domain → infra 箭頭）
> - [ ] 每個元件有 provided + required interface（非只方法名，含錯誤行為）
> - [ ] Risks ≥ 3（含 leaky abstraction / temporal coupling / circular DI）
> - [ ] 無 YAML / JSON schema 輸出（用 mermaid + 表格表達）