ADR-DS-000_개요

1. 기본 정보

• ADR ID: ADR-DS-000
• 제목: Domain State and Payment Model Overview
• 상태: Accepted
• 작성일: 2026-03-08
• 작성자: YSY
• 관련 ADR: ADR-DS-010, ADR-DS-012, ADR-DS-015, ADR-DS-020, ADR-DS-064
• Supersedes: N/A
• Superseded By: N/A

2. 목적

도메인 핵심 논리를 상위 개요 문서로 고정한다.

• Slot 상태와 Reservation 상태를 분리한다.
• 결제 방식(payment_method)과 확인 방식(verification_method)을 분리한다.
• 경합 제어와 상태 전이 기록 책임을 분리한다.
• 문서 개정 시 전수 수정 대신 적용 범위와 정합성 규칙으로 운영한다.

3. 상태 모델

3.1 Slot State Machine

issued | closed

• issued: 예약 수락 가능
• closed: 예약 수락 종료(시간 경과, 운영 종료, 정책 종료)

3.2 Reservation State Machine

reserved | redeemed | expired | cancelled

허용 전이:

reserved -> redeemed
reserved -> expired
reserved -> cancelled

종결 상태:

redeemed | expired | cancelled

4. 결제/확인 축

4.1 payment_method

on_site | prepaid

• 기본값: on_site
• prepaid는 파트너 정책과 회원 등급/업종 조건을 만족할 때만 허용

4.2 verification_method

none | location | qr

• none: 추가 확인 없이 확정 가능
• location: 위치 검증 성공 시 확정
• qr: QR 검증 성공 시 확정

4.3 축 분리 원칙

• payment_method와 verification_method는 독립 축이다.
• 결제 성공/실패는 결제 도메인 이벤트로 기록한다.
• Reservation 상태 집합 자체는 결제 방식에 의해 확장하지 않는다.

5. Hold(임시 점유) 개념

• 결제 진행 중 동시 점유 방지를 위해 hold 개념을 사용한다.
• hold는 Reservation 상태와 분리된 별도 도메인으로 관리한다.
• 상세 정책(TTL, 해제, 결제 연계)은 별도 ADR에서 정의한다.

6. 기본 전이 규칙

• Slot이 issued가 되었다고 Reservation을 미리 생성하지 않는다.
• Reservation은 실제 예약 액션 시 1건 생성된다.
• 수량 차감은 reserved -> redeemed 전이와 같은 서버 트랜잭션에서만 수행한다.

추가 정책:

• prepaid + verification_method=none은 결제 성공 시 즉시 redeemed 전이를 허용할 수 있다.
• prepaid + (location|qr)는 결제 성공 후에도 검증 성공 시점에 redeemed 전이한다.

7. 만료/시간 상한

• 만료 시각(expires_at)은 파트너가 슬롯별 정책으로 설정할 수 있다.
• 단, 운영 상한을 강제한다:
  • expires_at <= store_close_at
  • 필요 시 expires_at <= slot_end_at + max_grace

8. 용어 폐기(Deprecation)

Domain 표준 용어에서 아래 용어를 제거한다.

• arrived
• checkin / check_in

대체:

• 상태 용어: redeemed
• 사용자 액션 용어: redeem 또는 use confirmation

9. 적용 범위 및 정합성 운영 규칙

9.1 Effective Scope

• DS-000 모델은 ADR-DS-060 이후 변경분에 우선 적용한다.
• 이전 문서는 즉시 전수 개정하지 않고 점진 정합화한다.

9.2 Conformance 표기

하위 ADR 상단에 다음 3개를 명시한다.

• Conforms to: ADR-DS-000 v1
• Effective from: ADR-DS-060+ (또는 명시적 날짜)
• If conflict: ADR-DS-000 wins

9.3 개정 원칙

• DS-000 개정 시 모든 문서를 즉시 전수 수정하지 않는다.
• 하위 문서는 touch 시점에 함께 정합화한다.
• 충돌 가능성이 큰 문서는 상단 주의 노트로 우선 제어한다.

10. 서버 권한 원칙

• 상태 확정은 서버만 수행한다.
• 클라이언트는 요청/표시만 수행한다.
• 만료 확정과 최종 상태 판정은 서버 시간 기준으로 수행한다.

11. 단일 출처(SoT)

• 상태 전이 SoT: ADR-DS-010
• 시간/만료 SoT: ADR-DS-012
• 무결성 SoT: ADR-DS-015
• 사용 확정 SoT: ADR-DS-020
• 수량/동시성 SoT: ADR-DS-064

본 ADR(DS-000)은 상위 개요 문서이며, 세부 정책은 각 ADR이 소유한다.

12. 후속 ADR 맵

아래 항목은 DS-000에서 요약만 다루고, 상세는 개별 ADR에서 관리한다.

1. 상태 전이 권한: ADR-DS-023
2. 취소 사유 분류: ADR-DS-024
3. 멱등성 규칙: ADR-DS-025
4. 서버 시간/타임존 경계: ADR-DS-026
5. Hold-Reservation 연결 규칙: ADR-DS-027
6. 수량 계산 SoT 공식: ADR-DS-028
7. 도메인 실패 코드 표준: ADR-DS-029
8. 감사로그 최소 스키마: ADR-DS-031

Buy me a coffee