refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -0,0 +1,58 @@
+---
+id:
+kind: CONCEPT
+slug: three-failure-vocabularies
+title: 실패 어휘 세 층과 그 사이를 잇는 SQLState 매트릭스
+topic: http-failure-classification
+topicName: HTTP 실패 분류와 재시도 안전성
+project: clean-architecture-backend-template
+status: 게시 전
+studio: ""
+basisVersion: sourceRevision 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+source:
+  - final/document.md#a02
+  - final/document.md#a05
+  - final/document.md#5-1
+  - final/document.md#a05 §7.1
+  - final/document.md#a02
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+---
+
+# 실패 어휘 세 층과 그 사이를 잇는 SQLState 매트릭스
+
+저수준 driver 오류, 애플리케이션 failure category, 외부 HTTP 응답은 서로 다른 질문에 답한다. 이 프로젝트는 그 사이를 명시적 매핑으로 연결하고, 모르는 값은 추측하지 않는다.
+
+## 관계
+
+- **인식하지 못한 SQLSTATE 는 추측하지 않는다**
+  매트릭스에 없는 값을 임의의 failure category로 바꾸지 않는 결정이다.
+- **같은 SQLState 를 둘이 등록하면 값이 같아도 시작을 실패시킨다**
+  매핑 소유권을 한 곳으로 유지하는 규칙이다.
+- **전송 여부 판정은 evidence와 operation semantics를 함께 본다**
+  failure category가 곧 retry eligibility가 아니라는 후속 결정이다.
+
+## 본문
+
+<!-- body:start -->
+
+## 첫 번째 어휘는 공급자 오류다
+
+JDBC나 HTTP client는 SQLSTATE, status, exception type처럼 공급자에 가까운 값을 준다. 이 값은 어떤 기술 경계에서 실패했는지를 말하지만 애플리케이션 정책을 직접 결정하지 않는다.
+
+## 두 번째 어휘는 failure category다
+
+애플리케이션은 transient, conflict, unavailable처럼 정책이 이해할 수 있는 범주로 변환한다. PostgreSQL 경로에서는 SQLSTATE 매트릭스가 이 변환을 소유한다.
+
+매트릭스에 없는 SQLSTATE는 기존 항목과 비슷해 보인다는 이유로 추측하지 않는다. 새 매핑이 필요하면 그 소유자를 명시적으로 추가한다.
+
+## 세 번째 어휘는 외부 계약이다
+
+HTTP 응답은 클라이언트가 알아야 할 상태와 오류 코드를 표현한다. 내부 failure category와 1:1일 필요는 없고, 내부 구현 세부가 그대로 노출되어서도 안 된다.
+
+## retry는 별도 판정이다
+
+failure category는 retry 입력 중 하나다. 최종 retry eligibility는 전송 evidence, operation의 멱등성·의미, deadline과 retry budget을 함께 본다.
+
+현재 source repository를 다시 실행하지 못했으므로 이 기록은 SSOT가 고정한 매핑 구조를 설명한다.
+
+<!-- body:end -->