Module Design · 模組設計

---
doc_type: "module-design"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["c4-diagram", "adr"]
  optional: ["use-case", "non-functional-reqs"]
---

# Module Design: <service-name>

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

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 5 段（編號 1, 2, 3, 9, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每結論行內加 `（依據：c4-diagram §XXX / ADR-NNN）`；每欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造模組；**核心紀律：依賴方向單向、不成環 (acyclic)** — 模組圖的箭頭只能往一個方向流，任何雙向互指或回指上游的環必須在 Risks 段標為 violation 並提出拆解。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行說明本服務切成幾個模組、切分原則（單一責任）、依賴方向、最高風險 -->

<3-5 行說明：本服務拆幾個模組、為何這樣切、依賴方向、有無環>

> **TL;DR:** <一句話：N 個模組、依賴單向 acyclic、最該擔心的是 X 模組責任過載>

---

## 2. Module Map

<!-- ai-rule: 畫 graph LR / flowchart，箭頭代表「依賴」方向（A-->B 表示 A 依賴 B）。不能有環 -->

```mermaid
graph LR
    api[Order API\nroute + validation]
    domain[Order Domain\nstate machine]
    inventory[Inventory\nstock reservation]
    repo[Order Repository\nPostgres adapter]
    api --> domain
    domain --> inventory
    domain --> repo
    inventory --> repo
```

> 箭頭方向 = 依賴方向。上圖無回指（`repo` 不 import `domain`），確認 acyclic。（依據：c4-diagram §Order Service Components）

---

## 3. Responsibility Table

<!-- ai-rule: 每個模組單一責任。owns-data 寫該模組獨占的資料；public-interface 寫對外暴露的函式/介面 -->

| Module | Responsibility | Owns Data | Public Interface | Confidence |
|---|---|---|---|---|
| Order API | route handler + 入參驗證 | 無（無狀態） | `POST /orders`, `GET /orders/{id}` | **[H]** |
| Order Domain | order 狀態機 + 業務規則 | order aggregate（記憶體中） | `createOrder()`, `transition()` | **[H]** |
| Inventory | 庫存預留 / 釋放 | `inventory` 表 | `reserve(sku, qty)`, `release()` | **[H]** |
| Order Repository | Postgres 持久化 | `orders` 表 | `save()`, `findById()` | **[M]** |

---

## 9. Risks

<!-- ai-rule: 至少 3 個。必含 god module / cyclic dependency / leaky abstraction 三類各至少一 -->

> **R1（cyclic dependency）：** <e.g. 若 Inventory 為了發通知而 import Order Domain，會與既有 domain-->inventory 形成環> — **Severity:** H — **Mitigation:** 通知改由 Domain 透過 event 觸發，Inventory 不回指 — **Owner:** <SD>
>
> **R2（god module）：** <e.g. Order Domain 同時管狀態機 + 折扣 + 稅務，責任過載> — **Severity:** M — **Mitigation:** 折扣/稅務拆為獨立 Pricing 模組 — **Owner:** <SD>
>
> **R3（leaky abstraction）：** <e.g. Order API 直接吃 Repository 回傳的 ORM entity，繞過 Domain> — **Severity:** M — **Mitigation:** Repository 只回 domain object，不外洩 ORM 型別 — **Owner:** <Dev Lead>

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions（推測但 input 未明說）：**
  - <假設 1：例：假設 Inventory 與 Order 同庫，可同交易內預留>
- **Highest-value next input:** <下一份最該補的：class-diagram / 既有 codebase import graph>

### TODO（缺資料）

- _TODO: 需要 Dev Lead 確認 Inventory 是否與 Order 共用同一 DB 交易_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 5 段 H2 章節齊全（編號 1, 2, 3, 9, 12，刻意不連號）
> - [ ] Module Map 含 mermaid graph LR / flowchart
> - [ ] 依賴圖 acyclic（無回指、無雙向箭頭）
> - [ ] 每個模組單一責任（無 god module / 無 `common` 雜物袋）
> - [ ] Responsibility Table 每模組含 owns-data + public-interface
> - [ ] 每結論有 source（c4-diagram / ADR ref）
> - [ ] Risks ≥ 3（含 god module / cyclic / leaky abstraction）
> - [ ] 無 YAML / JSON schema 輸出（用 mermaid + 表格表達）