ADR
Topics
Verification Method 전이 규칙 통합

Verification Method 전이 규칙 통합

ADR-040 Verification Method 전이 규칙 통합

1. Metadata

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

2. Domain Decision

  1. verification_method는 none, location, qr로 고정한다.
  2. 검증 기반 전이는 payment_method와 독립적으로 동일하게 적용한다.
  3. reserved + none은 즉시 redeemed로 전이한다.
  4. reserved + location은 위치 검증 성공 시 redeemed로 전이한다.
  5. reserved + qr은 QR 스캔 성공 시 redeemed로 전이한다.
  6. on_site + location 검증은 주기 배치가 아니라 사용/수령 이벤트 시점 검증으로 처리한다.
  7. 위치 검증 실패 시 expired 전까지 QR 폴백을 기본 경로로 제공한다.
  8. 만료 시각 경과 후 미완료 건은 expired로 종료한다.
  9. 파트너 보조 검증은 상태 전이를 추가하지 않고 redeemed 이후 증적 기록으로만 처리한다.
  10. 보조 검증 필드는 partner_verified, partner_verified_at, partner_verified_by_store_id로 고정한다.

3. Product Decision

  1. verification_method는 슬롯 발행 시점에 선택한다.
  2. 위치 검증 실패 시 만료 전 QR 폴백을 기본으로 제공한다.
  3. 결제 방식(payment_method)과 완료 조건(verification_method)의 역할을 분리한다.
  4. 검증 완료 시점의 사용자 안내 기준을 통일한다.

4. UX Decision

  1. Verification UX의 단일 SoT는 SPEC-000의 UX Rule Catalog를 따른다.
  2. 검증 단계의 화면/CTA/실패 처리 상세는 UX-R-002/003/006/007/009/011을 참조한다.
  3. 위치 실패 QR 폴백 및 멱등 재노출 기준은 UX-R-006/012로 관리한다.

5. Tech Decision

  1. 검증 이벤트는 방식별 공통 인터페이스로 처리한다.
  2. 위치 검증 호출은 주기 작업이 아닌 이벤트 트리거로 처리한다.
  3. 위치 실패 이벤트는 QR 폴백 이벤트로 연결한다.
  4. 검증 완료 이벤트는 상태 전이와 감사로그를 함께 기록한다.

6. Ops Decision

  1. 검증 실패 원인 분류와 대응 절차를 정의한다.
  2. 위치 실패-QR 폴백 문의 대응 스크립트를 운영한다.
  3. 반복 실패 파트너/사용자 모니터링을 수행한다.

7. Implementation Contract (Optional)

7.1 API Contract

  • 검증 요청은 verification_method를 필수 입력으로 받는다.
  • 위치 검증 실패 응답은 QR 폴백 가능 여부(fallback=qr)와 만료 전 잔여 시간(expires_in_sec)을 포함한다.

7.2 Data Contract

  • verification_method 허용값은 none|location|qr로 고정한다.
  • 보조 검증 필드는 partner_verified, partner_verified_at, partner_verified_by_store_id만 사용한다.

7.3 Error/Observability Contract

  • VERIFICATION_METHOD_MISMATCH, LOCATION_VERIFY_FAILED, VERIFICATION_EXPIRED 코드를 분리한다.
  • 검증 완료/실패 이벤트를 상태 전이 이벤트와 함께 기록한다.

7.4 Test/Acceptance Contract

  • prepaid+none은 결제 성공 직후 즉시 redeemed로 확정되어야 한다.
  • prepaid+qr은 QR 성공 시점에만 redeemed로 확정되어야 한다.
  • on_site+location은 이벤트 시점 검증만 수행하고 주기 검증을 수행하지 않아야 한다.
  • on_site+location 실패 시 만료 전 QR 폴백 경로가 항상 노출되어야 한다.
  • UX 수용 기준 검증은 SPEC-000의 UX-R-006/007/009/011/012 준수 여부로 판정한다.

8. Validation

  • Domain/Product/UX/Tech/Ops 결정이 충돌하지 않는다.
  • 구현 기준은 SPEC과 정합성을 유지한다.
  • 운영 절차는 RUNBOOK으로 연결된다.
Buy me a coffee Buy me a coffee
Hold 및 결제 상태 전이 통합상태 전이 권한 규칙 통합