Hold 및 결제 상태 전이 통합
ADR-030 Hold 및 결제 상태 전이 통합
1. Metadata
- ADR ID: ADR-030
- Status: draft
- Date: 2026-03-09
- Owner: YSY
2. Domain Decision
hold는 결제 진행 중 임시 점유 상태로만 사용한다.- Hold 만료 기본값은
90초, 최대값은 180초로 한다. - 결제 재시도 기본값은
2회로 한다. (운영 파라미터로 조정 가능) payment_method=prepaid 결제 성공 시 상태는 최소 reserved로 확정한다.payment_method=on_site는 결제 단계 없이 reserved로 진입한다.redeemed 전환은 verification_method 조건으로 처리한다. (none|location|qr)verification_method=none이면 reserved -> redeemed를 즉시 전환한다. (prepaid/on_site 공통)- 결제 실패/타임아웃 시
expired 또는 cancelled로 전이한다. - 동일 사용자+슬롯 조합에 대해 활성 hold 중복 생성은 허용하지 않는다.
- hold와 reservation 간 참조 무결성을 유지한다.
3. Product Decision
- Hold 단계는 결제 완료 전 임시 점유로 정의한다.
- Hold 시간 정책은 기본 90초, 최대 180초를 사용한다.
- 결제 재시도는 기본 2회로 운영한다.
prepaid 성공은 예약 확정(reserved)까지를 보장한다.- 최종 완료(
redeemed)는 검증 방식(none|location|qr)에 따라 분기한다. - 결제 실패/만료 시 환불 없이 종료 상태로 전이한다.
4. UX Decision
- Hold/결제 전이의 UX 단일 SoT는
SPEC-000의 UX Rule Catalog를 따른다. - 본 ADR은 도메인 전이 정책만 정의하고, 화면 단계/CTA/문구 상세는
UX-R-001/002/003/004/005를 참조한다. - 시나리오 기반 UX 변경은
SCENARIO 갱신 후 SPEC-000 Rule ID 갱신으로 반영한다.
5. Tech Decision
- Hold 생성/전환/만료를 트랜잭션 경계로 관리한다.
- 결제 결과 확정 시
reserved 전이를 원자적으로 처리한다. - 재시도 요청은 멱등키로 중복 처리한다.
- Hold 만료 기본값 90초, 최대값 180초, 재시도 2회를 기본 설정으로 사용한다.
6. Ops Decision
- Hold 만료 배치를 주기적으로 실행한다.
- 배치 실패 시 재실행 절차를 표준화한다.
- 스케줄 변경은 운영 이력으로 관리한다.
- 기본 배치 주기는 1분이며, 변경 시 공지/이력 기록을 남긴다.
7. Implementation Contract (Optional)
7.1 API Contract
- Hold 생성 응답은
hold_id, expires_at_utc, retry_remaining을 반환한다. - 결제 확정/실패 콜백은
idempotency_key로 중복 처리한다. - 결제 성공 응답은 최소
reservation_status=reserved, next_required_step(none|location|qr)를 포함한다.
7.2 Data Contract
- 동일
user_id + slot_id의 활성 hold 중복 생성은 금지한다. - Hold TTL은
90~180초 범위로만 저장한다. - 결제 성공 시
reserved_at_utc를 필수 기록한다.
7.3 Error/Observability Contract
HOLD_ALREADY_EXISTS, HOLD_EXPIRED, PAYMENT_CONFIRM_TIMEOUT 코드를 표준화한다.- Hold 생성/만료/결제확정/예약확정 이벤트를 감사로그에 필수 기록한다.
7.4 Test/Acceptance Contract
prepaid+none은 결제 성공 직후 reserved -> redeemed가 즉시 수행되어야 한다.prepaid+qr/prepaid+location은 결제 성공 시점에는 reserved를 유지해야 한다.- 결제 실패/타임아웃 시
expired|cancelled로만 종료되어야 한다. - UX 수용 기준 검증은
SPEC-000의 UX-R-001/002/003/004/005 준수 여부로 판정한다.
8. Validation
Buy me a coffee