# KBX External Integration & Resilience Governance v19

## 1. 목적
외부연계 실패를 Business Transaction 실패와 혼동하지 않는다. Domain Commit이 완료되었다면 사용자는 동일 저장/확정 Command를 반복하지 않는다.

## 2. 상태 분리
`Business State`와 `Integration State`는 별도다.

예: 주문 확정 완료 / WMS 출고지시 전송 대기.

## 3. Retry 책임
- Polly: 요청 수명 안의 짧은 transient retry/timeout/circuit breaker.
- Hangfire: 프로세스 재시작을 견뎌야 하는 durable retry.
- Outbox/Inbox: 전달 유실/중복 방지.
- PostgreSQL: attempt/receipt의 source of truth.

Polly retry를 장시간 스케줄러처럼 사용하지 않는다.

## 4. 실패 분류
Transient: network, timeout, HTTP 408/429/5xx, circuit-open.
Permanent: contract-invalid, HTTP 400/401/403/404, domain-rejected.

Permanent 실패는 자동 retry하지 않고 Operations Exception으로 승격한다.

## 5. 사용자 UX
정상 저장 성공 후 연계 지연은 `저장 실패`가 아니다.

- 업무: 완료
- 연계: 전송 대기 / 자동 재시도 / 실패

사용자가 업무 Command를 다시 눌러 중복 데이터를 만들지 않게 한다.

## 6. 특정 외부 서비스
현재 첨부 KBX 기준 문서에는 KRX/OPENDART/KIS의 실제 Endpoint/Quota/Auth 규칙이 정의되어 있지 않으므로 v19 계약에는 임의로 넣지 않았다. 각 Adapter 온보딩 시 공식 공급자 문서를 기준으로 별도 Integration Definition을 추가한다.