CSP-003　錯誤處理與回應碼規範（Error Handling & Response Code）

1. 目的

統一全系統之錯誤分類、錯誤碼、HTTP 狀態對應、回應封套與例外處理策略，
確保：①前端可據錯誤碼精準處理；②不洩漏內部實作；③可觀測、可追蹤。

2. 錯誤碼分類

錯誤碼格式：CC-<SVC>-<NNNN>，其中 <SVC> 為 2–4 字母服務代碼（依服務別長度不一：如 AUTH=4、LIM=3、GW=2），與 SDD-006 §3.2 登錄表、OpenAPI Error.code 之 ^CC-[A-Z]{2,4}-[0-9]{4}$ 完全一致。

唯一登錄表：所有可用錯誤碼以 SDD-006 §3.4 為準（共 50+ 碼）。Coder 不得自創錯誤碼；新增碼須先擴充 SDD-006 §3.4 並同步 gen_openapi.py 之 Error.code.pattern。

| 類別位（首位） | 意義 | HTTP | 可否重試 | 代表碼 |
|---:|---|---|:--:|:--:|---|
| 1 | 業務規則拒絕 | 422 | ❌ | CC-AUTH-1001、CC-LIM-1001、CC-POST-1001 |
| 2 | 併發／冪等衝突 | 409 | 部分可 | CC-POST-2001、CC-POST-2002 |
| 3 | 狀態機衝突 | 409 | ❌ | CC-CARD-3001、CC-POST-3001 |
| 4 | 請求與資源 | 400 / 404 / 405 / 409 | ❌ | CC-PLT-4001、CC-PLT-4002、CC-PLT-4003、CC-PLT-4040、CC-PLT-4050、CC-POST-4001 |
| 5 | 外部與基礎設施 | 503 / 500 | ✅（冪等者） | CC-PLT-5000、CC-PLT-5001、CC-PLT-5002、CC-AUTH-5001 |

v1.2 更正：原表類別位 4 之代表碼誤引 CC-AUTH-4004——該碼不存在於
SDD-006 §3.4 登錄表（登錄表目前尚無任何 404 碼）。依本文件 §2「唯一登錄表」原則，
更正為已登錄之 CC-POST-4001／CC-POST-4002。
若日後確有「資源不存在」情境，應先擴充 SDD-006 §3.4 再使用，不得直接引用未登錄碼。

2.1 類別位 4「請求與資源」之語意（v1.3 擴充，CR-004）

類別位 4 ＝「請求本身或其所指資源無法被受理」，涵蓋四個子語意，
皆屬請求層，尚未進入業務邏輯：

與其他類別位之區別（選碼判準）：

⚠️ 不得用類別位 5（5xx）掩飾請求層錯誤——此即 CSP-003 §7 E3「用 500 掩飾所有錯誤」
所禁止之行為：前端無法區分、監控告警失準。請求層錯誤若回 500，每個客戶端誤用都會觸發
ERROR 告警，造成告警疲勞，真正的伺服器異常將被淹沒。

實作歸屬：本類別位之 CC-PLT-4xxx 五碼由 common-spring 之 GlobalExceptionHandler
統一拋出，服務不需自行實作。服務僅在需要更精確語意時才使用自有 4xxx 碼
（如 CC-PTY-4040「歸戶查無」）。Spring 例外之對應關係見 SDD-006 §3.4。

HTTP 狀態對應原則：

服務代碼總表（摘要）：AUTH(4) CARD(4) POST(4) LIM(3) PTY(3) PRD(3) PAY(3) STM(3) PRC(3) INS(3) RWD(3) CLR(3) DSP(3) MRC(3) NOT(3) RPT(3) MIG(3) PLT(3) GW(2)。不存在 CMN 等偽代碼。

3. 回應封套（統一格式）

所有回應（成功與失敗）一律套用統一信封（與 OpenAPI Envelope / Error schema 完全一致）：

{
  "traceId": "01HZX8K2M4N5P6Q7R8S9T0V1W2",
  "data": { },
  "error": null
}

失敗時 data 為 null，error 攜帶結構化資訊：

{
  "traceId": "01HZX8K2M4N5P6Q7R8S9T0V1W2",
  "data": null,
  "error": {
    "code": "CC-LIM-1001",
    "message": "可用額度不足",
    "details": [
      { "field": "amount", "reason": "exceeds available limit" }
    ]
  }
}

禁止（對應 CSP-001 §8 B4）：不得將例外堆疊、SQL 語句、框架內部錯誤原樣回傳。
內部錯誤一律轉為 CC-PLT-5xxx + 通用訊息，細節僅寫入伺服器日誌（含 traceId）。

4. 例外處理階層

classDiagram
    class DomainException {
        +String code
        +String message
    }
    class ValidationException
    class BusinessRuleException
    class ConcurrencyException
    class InfrastructureException
    class DownstreamException
    DomainException <|-- ValidationException
    DomainException <|-- BusinessRuleException
    DomainException <|-- ConcurrencyException
    DomainException <|-- InfrastructureException
    InfrastructureException <|-- DownstreamException

• domain/ 拋出 DomainException 子類（業務語意），不含技術細節。
• interfaces/ 設 ControllerAdvice 將 DomainException 映對為 HTTP 狀態＋封套。
• infrastructure/ 將 JDBC／HTTP 錯誤包裝為 InfrastructureException，不向上洩漏。

5. 冪等與重試

1. 冪等鍵：所有寫側 Command（授權、入帳、繳款…）攜帶 Idempotency-Key（ client 產生或上游傳入）；
   重複提交返回首次結果，不重複執行（SDD-004 §幂等）。
2. 重試：下游暫態失敗（503 服務不可用／外部逾時）由呼叫方以指數退避重試（上限 3 次，含 jitter）；
   非暫態（4xx）不重試。
3. 逾時：同步呼叫下游預設 800ms 逾時；超過即 CC-PLT-5001（外部系統逾時）並觸發 Stand-in / 補償（SDD-004）。

6. 交易與補償語意

• 寫側一律在 application/ 層開交易；跨服務透過 Saga + Outbox（SDD-004）保證最終一致。
• 補償失敗（如回退視窗逾時、補償步驟失敗）拋 CC-PLT-5002（Saga 補償失敗），由協調者告警並進入人工處置佇列；
  與遷移相關之失敗使用 CC-MIG-1001（遷移類型不支援）等 MIG 登錄碼，不得自創。

7. 禁止事項

8. 變更記錄