# 整合邊界設計 (Integration Boundary Design) 知識合約指南

## 概述
`integration-boundary-design` 是知識合約，用來提供整合邊界設計的原則與模式。涵蓋外部 API 整合、Webhook 處理、Polling、重試策略、速率限制與失敗模式處理。供 `design-architecture` 在定義 Integration Boundaries 時參考。

## 核心原則
### 整合隔離
- 外部系統失敗不得級聯到系統失敗
- Circuit Breaker 必須保護內部服務
- 整合程式碼必須與商業邏輯隔離（Anti-Corruption Layer）

### 明確合約
- 每個外部整合必須有明確定義的合約
- 合約必須包含請求/回應結構、錯誤碼與 SLA
- 變更必須版本化並盡可能向後相容

### 假設失敗
- 外部系統會失敗、逾時、返回非預期資料
- 必須為每個整合定義逾時、重試與回退

## 設計重點
- **外部 API 整合**：同步呼叫、非同步呼叫、Batch 呼叫、串流
- **Webhook 處理**：Inbound Webhooks（接收）與 Outbound Webhooks（發送）
- **Polling**：增量 Polling、輪詢間隔與資料差距處理
- **重試策略**：退避策略、重試預算、最大總重試時間
- **速率限制**：Token Bucket、Leaky Bucket、Fixed Window、Sliding Window
- **失敗模式處理**：Transient、Permanent、Partial、Cascading Failure

## 知識合約職責
- 提供整合邊界設計的理論指引
- 不直接產生整合合約或實作程式碼

## 不應做的事
- 不替特定外部系統選擇整合方式
- 不定義具體的逾時值或重試次數
- 不產生實作程式碼