Sequence Diagram · 時序圖

---
doc_type: "sequence-diagram"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["use-case", "api-spec"]
  optional: ["adr"]
---

# Sequence: <use-case-name>

**Status:** Draft · **Owner:** <SA/Architect> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 5 段（編號 1, 2, 3, 6, 12），全部必填——刻意沿用完整版的章節編號讓兩版可對照。每條 message 行內加 `（依據：api-spec §endpoint）`；每欄位帶 `[H]/[M]/[L]` confidence badge；缺資料寫 `_TODO: 需要 XXX_` 不編造服務；**至少畫 1 條 failure path**（純 happy path 不接受）；每條 retry 必含 backoff + max attempts + idempotency 標記。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行說明本流程涵蓋的 use case、跨幾個服務、主要 failure 點 -->

<3-5 行說明>

> **TL;DR:** <一句話：A → B → C 跨服務鏈，主要 failure 點在 X>

---

## 2. Happy Path

```mermaid
sequenceDiagram
    actor User
    participant FE as Web FE
    participant API as Order API
    participant DB as Order DB
    User->>FE: submit order
    FE->>API: POST /v1/orders (Idempotency-Key)
    API->>DB: INSERT order
    DB-->>API: ok
    API-->>FE: 201 Created
    FE-->>User: 顯示成功
```

### Messages

| Seq | From | To | Name | Sync/Async | Idempotency | Confidence |
|---|---|---|---|---|---|---|
| 1 | User | FE | submit order | sync | n/a | **[H]** |
| 2 | FE | API | POST /v1/orders | sync | required (header) | **[H]** |
| 3 | API | DB | INSERT order | sync | n/a (FK + uniq) | **[H]** |

---

## 3. Failure Path（至少 1 條）

### Path: API timeout

```mermaid
sequenceDiagram
    actor User
    participant FE as Web FE
    participant API as Order API
    User->>FE: submit order
    FE->>API: POST /v1/orders (Idempotency-Key=K)
    Note over API: > 5s no response
    FE-->>User: 顯示「處理中，請稍後重試」
    User->>FE: retry submit
    FE->>API: POST /v1/orders (same Idempotency-Key=K)
    API-->>FE: 201 Created (回原 response)
```

- **Trigger:** API > 5s 未回
- **Compensation:** client retry with same idempotency key；server 回原 response 而非建第二筆
- **Consumer visible:** FE 顯示「處理中，請稍後重試」

---

## 6. Idempotency & Timeout（核心）

| Endpoint | Idempotency-Key | TTL | On duplicate | Client timeout |
|---|---|---|---|---|
| `POST /v1/orders` | required (UUID v4) | 24h | 回原 response | 5s |

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions（推測但 input 未明說）：**
  - <假設 1：例：假設 client 會帶 Idempotency-Key>
- **Highest-value next input:** <下一份最該補的：實測 timeout 分布 / SRE alert 策略>

### TODO（缺資料）

- _TODO: 需要 SRE 確認 5s timeout 是否與 SLO 一致_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 5 段 H2 章節齊全（編號 1, 2, 3, 6, 12，刻意不連號）
> - [ ] Happy Path 含 mermaid sequenceDiagram
> - [ ] Failure Path 至少 1 條（純 happy 不接受）
> - [ ] 每條 POST/PATCH message 標 Idempotency-Key
> - [ ] 每個 client 呼叫標 timeout
> - [ ] 無 YAML / JSON schema 輸出（用 mermaid + 表格表達）