멱등성 및 중복 요청 처리 통합

ADR-070 멱등성 및 중복 요청 처리 통합

1. Metadata

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

2. Domain Decision

1. 상태 변경 요청은 멱등키 기준으로 1회 확정 처리한다.
2. 재시도 요청은 기존 결과를 재반환한다.
3. 중복 결제/중복 전이를 서버에서 차단한다.

3. Product Decision

• 해당 없음

4. UX Decision

• 해당 없음

5. Tech Decision

1. 상태 변경 API는 멱등키를 필수로 지원한다.
2. 재처리 큐는 중복 실행 방지 키를 사용한다.
3. 중복 요청 결과는 동일 응답을 반환한다.

6. Ops Decision

1. 재처리 트리거 조건과 승인 절차를 정의한다.
2. 재처리 전/후 검증 체크리스트를 운영한다.
3. 재처리 결과를 감사 로그로 남긴다.

7. Implementation Contract (Optional)

7.1 API Contract

• 상태 변경 API는 idempotency_key를 필수로 받는다.
• 동일 키 재요청은 최초 응답을 그대로 재반환한다.

7.2 Data Contract

• 멱등 저장소는 actor + command + idempotency_key 유니크 제약을 가진다.
• 멱등 레코드는 재시도 정책에 맞는 TTL을 유지한다.

7.3 Error/Observability Contract

• 멱등키 누락은 IDEMPOTENCY_KEY_REQUIRED로 반환한다.
• 중복 요청/재반환 건수를 모니터링 지표로 수집한다.

7.4 Test/Acceptance Contract

• 네트워크 재시도 2회 이상에도 비즈니스 결과는 1회만 확정되어야 한다.
• 동일 요청 재전송 시 응답 payload가 동일해야 한다.
• 첫 예약 플로우에서 동일 요청 재전송 시 결과 상태와 후속 액션이 동일해야 한다.

8. Validation

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

Buy me a coffee