슬롯 기반 예약 시스템 백엔드 설계 - 가상 슬롯, 점유 계산, advisory lock

class FacilityResource(models.Model):
    """시설 설정. 슬롯 생성의 '규칙'만 가진다."""
    place = models.OneToOneField("Place", on_delete=models.PROTECT)
    capacity = models.PositiveIntegerField("기본 정원")
    slot_minutes = models.PositiveIntegerField("슬롯 단위(분)", default=20)
    max_slots_per_reservation = models.PositiveIntegerField(default=3)
    advance_booking_days = models.PositiveIntegerField("예약 가능 일수", default=14)
    # 요일별 운영시간은 별도 WeeklySchedule 모델 (7 row)

def build_time_grid(open_time, close_time, slot_minutes):
    """[open, open+slot, ...] 슬롯 시각 리스트. close를 넘는 슬롯은 제외."""
    grid = []
    cursor = datetime.combine(date.min, open_time)
    end = datetime.combine(date.min, close_time)
    delta = timedelta(minutes=slot_minutes)
    while cursor + delta <= end:
        grid.append(cursor.time())
        cursor += delta
    return grid

build_time_grid(time(6, 0), time(23, 0), 20)
# [06:00, 06:20, ..., 22:40]  (51개)

class FacilitySlotException(models.Model):
    """기본 규칙에서 벗어나는 슬롯만 row 생성. 평상시 이 테이블은 거의 비어있다."""
    resource = models.ForeignKey(FacilityResource, on_delete=models.CASCADE)
    date = models.DateField()
    slot_time = models.TimeField()
    is_closed = models.BooleanField(default=False)      # True면 예약 불가 (대관·점검)
    capacity_override = models.PositiveIntegerField(    # null이면 기본 정원 사용
        null=True, blank=True, default=None
    )
    note = models.CharField(max_length=200, blank=True, default="")  # "단체 대관" 등

    class Meta:
        constraints = [
            models.UniqueConstraint(
                fields=["resource", "date", "slot_time"],
                name="uniq_slot_exception",
            ),
        ]

class FacilityReservation(models.Model):
    resource = models.ForeignKey(FacilityResource, on_delete=models.PROTECT)
    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT)
    membership = models.ForeignKey("Membership", on_delete=models.PROTECT)

    date = models.DateField("예약 날짜")
    start_time = models.TimeField("시작 시각")
    slot_count = models.PositiveIntegerField("배정된 슬롯 수")  # 1~3

    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default="RESERVED")

    class Meta:
        indexes = [
            models.Index(fields=["user", "date"]),
            models.Index(fields=["resource", "date", "status"]),
            models.Index(fields=["resource", "date", "start_time"]),
        ]

def slot_occupancy(slot_start, slot_end, reservations, slot_minutes):
    """겹침 조건: r.start < slot_end AND r.end > slot_start"""
    count = 0
    for r in reservations:
        r_end = add_minutes(r.start_time, r.slot_count * slot_minutes)
        if r.start_time < slot_end and r_end > slot_start:
            count += 1
    return count

def make_resource_date_lock_id(resource_id: int, target_date: date) -> int:
    """(자원, 날짜) 조합을 bigint 락 키로 변환"""
    return (resource_id << 32) | int(target_date.strftime("%Y%m%d"))

def pg_advisory_xact_lock(lock_id: int):
    """트랜잭션 종료시 자동 해제되는 advisory lock"""
    if not transaction.get_connection().in_atomic_block:
        raise RuntimeError("advisory lock은 transaction.atomic 안에서 호출해야 합니다.")
    with connection.cursor() as cursor:
        cursor.execute("SELECT pg_advisory_xact_lock(%s)", [lock_id])

with transaction.atomic():
    # 같은 (시설, 날짜)에 대한 예약 생성을 직렬화
    pg_advisory_xact_lock(make_resource_date_lock_id(resource.id, target_date))

    # 이 안에서의 잔여 계산은 동시 요청으로부터 안전하다
    validate_capacity(resource, target_date, start_time, slot_count)
    reservation = FacilityReservation.objects.create(...)

GET /api/facility/eligibility/

{
  "is_eligible": false,
  "reason_code": "FACILITY_0004",
  "reason": "미납된 추가요금이 있습니다.",
  "remaining_credits": 2
}

class FacilityReservation(models.Model):
    ...
    # 체크인 시점의 정책 값을 고정
    price_per_extra_slot_snapshot = models.PositiveIntegerField(default=0)
    extra_charge_grace_minutes_snapshot = models.PositiveIntegerField(default=0)

RESERVED ──> CHECKED_IN ──> CHECKED_OUT
    │
    ├──> NO_SHOW    (이용 종료 시각까지 체크인 없음, 배치 전환)
    └──> CANCELLED  (유저/관리자 취소)

CHECKOUT_TYPE_CHOICES = (
    ("manual_member", "수동(회원)"),
    ("manual_admin", "수동(관리자)"),
    ("forced_closing", "운영 종료 강제"),
    ("forced_max_slot", "최대 슬롯 도달 강제"),
)