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을 추가한다.

1.5 KiB Raw Blame History