2. ?? (Context)

? ?? ?? ?? ??/?? ?? ADR ?? ?? v2 ?? ???? ?? ??/?? ?? ?? ??. ?? ??/?? ?? ?? ??/?? ?? ?? ??.

상태: Draft (Updated)
작성일: 2026-03-02
Supersedes: ADR-DS-017
범위: Slot 당일 제한, usageVerifyGraceMinutes, expiresAt 산정, 사용 확정 허용 시간, 경계 조건, 서버 시간 기준

1. 목적

이 문서는 다음을 명확히 정의한다.

슬롯은 어떤 날짜 범위에서 유효한가
Reservation.expiresAt은 어떻게 계산되는가
사용 확정 허용 마감은 언제인가
만료는 언제 확정되는가
서버 시간과 클라이언트 시간의 역할

2. 슬롯 날짜 제한 (Day Constraint)

2.1 당일 한정 원칙

Slot.startAt과 Slot.endAt은 반드시 동일한 날짜(Asia/Seoul 기준)에 속해야 한다.

date(startAt) == date(endAt)

또한 슬롯은 “당일”에만 존재할 수 있다.

date(startAt) == date(serverNow)

즉:

오늘 19:00 슬롯은 오늘만 발행 가능
내일 19:00 슬롯은 오늘 발행할 수 없다

이로써 플랫폼은 장기 예약 서비스로 확장되지 않는다.

3. 만료시간 설정 방식

3.1 usageVerifyGraceMinutes

Slot에는 다음 필드가 존재한다.

usageVerifyGraceMinutes (int)

의미:

슬롯 시작 후 사용 확정을 허용하는 분 단위 시간

기본값 권장:

DEFAULT_usage_verify_GRACE = 15

가드레일:

0 <= usageVerifyGraceMinutes <= 30

4. expiresAt 산정 규칙

Reservation 생성 시 서버는 다음을 계산한다.

reservedAt = serverNow
expiresAt = slot.startAt + usageVerifyGraceMinutes minutes

중요:

expiresAt은 reservedAt과 무관하다.
예약은 “시작 시간 기준”으로 유효하다.

5. 사용 확정 허용 조건

사용 확정 허용은 아래 조건을 모두 만족해야 한다.

reservation.status == RESERVED
AND serverNow < expiresAt
AND 위치 조건 충족

정책:

사용 확정 허용은 strict 비교 <
만료 확정은 >=

즉,

if serverNow >= expiresAt → EXPIRED

6. 경계 조건 (Edge Cases)

6.1 serverNow == expiresAt

정의:

serverNow == expiresAt → 만료
사용 확정 불가

이렇게 하면 동일 시점에 두 조건이 동시에 참이 되는 모순을 제거한다.

6.2 슬롯 시작 이전 사용 확정 시도

만약 사용자가 slot.startAt 이전에 사용 확정을 시도하면:

정책 선택지 2가지가 있다.

Option A (권장)

사용 확정 허용 시점은 slot.startAt 이상으로 제한

serverNow >= slot.startAt

즉, 시작 전 사용 확정 금지.

Option B

시작 전에도 사용 확정 허용
도착 확인을 “사전 입장”으로 허용

구조적 단순성을 위해 Option A를 채택한다.

따라서 사용 확정 조건은:

reservation.status == RESERVED
AND slot.startAt <= serverNow < expiresAt
AND 위치 조건 충족

7. 만료 확정 책임

만료는 서버만 확정한다.

다음 시점에서 만료 판정이 발생할 수 있다.

reservation 조회 시
usage_verify 요청 시
백그라운드 정리 작업(선택)

클라이언트는 만료를 확정하지 않는다.

8. UI 타이머 계산

클라이언트는 다음을 계산할 수 있다.

remainingSeconds = max(0, expiresAt - effectiveNow)

effectiveNow는:

effectiveNow = clientNow + serverTimeOffset

단:

UI는 “만료 확인 중” 상태를 표시할 수 있으나
만료 확정은 서버 응답 기준이다.

9. 시간 불변 조건

expiresAt > slot.startAt (grace > 0일 경우)
expiresAt <= slot.endAt (권장 강제)
REDEEMED 상태는 항상:
```
slot.startAt <= redeemedAt < expiresAt
```
EXPIRED는:
```
serverNow >= expiresAt
```

10. 테스트 시나리오

T1

slot: 19:00~20:00, grace=15
expiresAt = 19:15
19:14 사용 확정 성공
19:15 사용 확정 실패

T2

12:00에 19:00 슬롯 예약 생성
expiresAt=19:15
18:59 사용 확정 불가 (시작 전)
19:00~19:14 사용 확정 가능

T3

grace=0
expiresAt=19:00
19:00 사용 확정 불가
사실상 시작 즉시 만료

T4

slot.endAt=19:10, grace=15
expiresAt=19:15 → 정책 위반
→ 발행 시 거절

11. 구조적 효과

이 모델은:

점심에 저녁 슬롯 예약 가능
장기 예약 불가
장시간 점유 없음
15분 구조 유지
예약 플랫폼으로 확장되지 않음

Template v2 Addendum

In Scope

Core domain rules (state/time/quantity/penalty/integrity/retention)

Out of Scope

Payment settlement, PG integration, UI behavior

Boundaries

Domain ADR defines policy. Implementation details belong to Tech ADR and code.

Source of Truth (SoT)

State model: ADR-DS-010; Time/expiry: ADR-DS-012; Quantity/concurrency: ADR-DS-064.

Validation

Detect state/constraint violations via tests and batch checks.
Recovery and reprocessing must be idempotent.

Revisit Conditions

KPI threshold breach (reservation failure, expiry ratio, payment confirmation failure)
External dependency change (PG, regulation, location API)

Buy me a coffee

ADR-DS-011_수량 차감 및 동시성 규칙 ADR-DS-013_발행 제한 계산 규칙

ADR-DS-012_확보 및 만료 시간 규칙