도메인 실패 코드 표준 통합

ADR-130 도메인 실패 코드 표준 통합

1. Metadata

• ADR ID: ADR-130
• Status: draft
• Date: 2026-03-09
• Owner: YSY

2. Domain Decision

1. 도메인 실패 코드를 의미 단위로 표준화한다.
2. 클라이언트 표시 문구는 코드 매핑으로 분리한다.
3. 신규 실패 코드는 하위 호환 기준을 따른다.

3. Product Decision

• 해당 없음

4. UX Decision

1. 도메인 실패 코드를 사용자 메시지로 매핑한다.
2. 행동 가능한 다음 단계 문구를 포함한다.
3. 동일 오류는 동일 톤/형식으로 노출한다.
4. 비즈니스 정책 오류와 시스템 오류를 시각적으로 구분한다.

5. Tech Decision

1. 도메인 실패 코드를 API 에러 포맷으로 표준화한다.
2. 클라이언트 매핑 테이블을 버전 관리한다.
3. 비표준 에러는 관측 가능하도록 별도 태깅한다.
4. 정책 오류와 시스템 오류 코드를 상위 카테고리로 분리한다.

6. Ops Decision

1. 표준 에러 코드 기반 모니터링 대시보드를 운영한다.
2. 중요 코드 알람/온콜 기준을 정의한다.
3. 주간 에러 리뷰로 우선순위를 관리한다.
4. 정책 오류와 시스템 오류를 분리해 알람 임계값을 운영한다.

7. Implementation Contract (Optional)

7.1 API Contract

• 오류 응답은 domain_code, category, retryable, message_key를 필수로 포함한다.
• category는 최소 policy|system으로 분리한다.

7.2 Data Contract

• 실패 코드 레지스트리는 코드/설명/사용자 메시지 키/재시도 여부를 버전 관리한다.
• 코드 재사용 시 의미 변경을 금지한다.

7.3 Error/Observability Contract

• 비표준 오류는 UNKNOWN_DOMAIN_ERROR로 포장하고 원인을 내부 태깅한다.
• 상위 오류 코드별 발생률/영향도를 운영 대시보드로 추적한다.

7.4 Test/Acceptance Contract

• 동일 domain_code는 채널(앱/웹)과 무관하게 동일 메시지 키로 매핑되어야 한다.
• 정책 오류/시스템 오류 시각 구분이 UI에서 일관되어야 한다.

8. Validation

• Domain/Product/UX/Tech/Ops 결정이 충돌하지 않는다.
• 구현 기준은 SPEC과 정합성을 유지한다.
• 운영 절차는 RUNBOOK으로 연결된다.

Buy me a coffee