본문으로 건너뛰기

Recording 예약 시스템 연동 가이드

문서 정보​

  • 작성일: 2026-02-19
  • 최종 업데이트: 2026-02-19
  • 버전: v1.0.0
TL;DR

WebSocket으로 fetch-info → reserve 순서로 호출하면 녹화 예약이 완료됩니다. 모든 시간은 UTC ISO8601로 전송하고, endTime = startTime + recordingInterval로 계산합니다.

목차​

  1. 전체 플로우
  2. fetch-info: 체육관 정보 조회
  3. reserve: 예약 생성
  4. 운영시간 이해하기
  5. 서버 검증 과정
  6. 왜 UTC → KST 변환이 필요한가?
  7. FAQ

전체 플로우​

fetch-info: 체육관 정보 조회​

예약 전에 반드시 fetch-info를 먼저 호출해야 합니다.

응답 예시​

{
  "data": {
    "gym": {
      "uuid": "0198fbbb-e03e-...",
      "gymCode": "8ec9c43b...",
      "name": "이동국 FC",
      "operatingHours": [
        { "day": "MONDAY", "openTime": "00:00", "closeTime": "24:00" },
        { "day": "TUESDAY", "openTime": "09:00", "closeTime": "24:00" },
        { "day": "WEDNESDAY", "openTime": "09:00", "closeTime": "24:00" },
        // ...
      ],
    },
    "court": {
      "uuid": "0198fbbb-e4e4-...",
      "name": "실내 A, B 구장",
      "recordingInterval": 60,
    },
  },
}

클라이언트가 사용할 핵심 값:

필드설명용도
operatingHours요일별 운영시간 (KST)예약 가능 시간대 UI 표시
recordingInterval녹화 1회 길이 (분)endTime 계산에 사용

reserve: 예약 생성​

요청 형식​

{
  gymUuid: string;                 // fetch-info에서 받은 gym.uuid
  courtUuid: string;               // fetch-info에서 받은 court.uuid
  startTime: string;               // ISO8601 UTC
  endTime: string;                 // ISO8601 UTC
  triggeredAt: string;             // ISO8601 UTC (버튼 클릭 시점)
  portraitRightsConsent: boolean;   // 초상권 동의 (필수: true)
  latitude?: number;               // GPS 위도 (선택)
  longitude?: number;              // GPS 경도 (선택)
}

시간 계산 방법​

핵심 규칙
  • 모든 시간은 UTC ISO8601 형식으로 전송
  • endTime = startTime + recordingInterval(분)
  • triggeredAt은 반드시 startTime ~ endTime 사이

예시: recordingInterval = 60분​

사용자가 KST 2026-02-19 14:30에 예약 버튼을 누른 경우:

{
  "gymUuid": "0198fbbb-e03e-...",
  "courtUuid": "0198fbbb-e4e4-...",
  "startTime": "2026-02-19T05:00:00.000Z", // KST 14:00
  "endTime": "2026-02-19T06:00:00.000Z", // KST 15:00 (14:00 + 60분)
  "triggeredAt": "2026-02-19T05:30:00.000Z", // KST 14:30 (버튼 누른 시점)
  "portraitRightsConsent": true,
}

운영시간 이해하기​

운영시간은 KST 기준으로 저장되며, 3가지 패턴이 있습니다.

언제 뭘 쓸까?​

패턴openTime-closeTime판단 기준의미
일반 운영09:00-24:00openTime < closeTime당일 09시 ~ 자정
24시간 운영00:00-24:00openTime=00:00, closeTime=24:00하루 종일
새벽/자정 넘김18:00-03:00openTime > closeTime당일 18시 ~ 익일 03시
자정 넘김 판단법

openTime > closeTime이면 자정을 넘기는 운영시간입니다. 클라이언트는 이 조건으로 UI에 다음 날까지 표시해야 합니다.

자정 넘김 시각화​

금요일 18:00-03:00 = 금요일 18시부터 토요일 03시까지 연속 운영

자정 넘김 예약 예시​

체육관 운영시간이 금요일 18:00-03:00일 때, 사용자가 KST 토요일 01:30에 예약:

{
  "startTime": "2026-02-20T16:00:00.000Z", // KST 토 01:00
  "endTime": "2026-02-20T17:00:00.000Z", // KST 토 02:00
  "triggeredAt": "2026-02-20T16:30:00.000Z", // KST 토 01:30
}
클라이언트는 자정 넘김 검증 로직을 몰라도 됩니다

UTC 시간만 정확히 보내면 서버가 알아서 처리합니다. 서버는 당일 운영시간 체크 후, 전날 자정 넘김 여부까지 자동으로 확인합니다.

서버 검증 과정​

예약 요청이 서버에 도착하면 8단계 검증을 순서대로 수행합니다.

에러 코드 참조​

단계검증에러 코드
1fetch-info 선행 호출 필수VALIDATED_GYM_NOT_SET / VALIDATED_COURT_NOT_SET
2gymUuid/courtUuid 일치VALIDATED_GYM_MISMATCH / VALIDATED_COURT_MISMATCH
3동시 녹화 불가ALREADY_RECORDING
5운영시간 내 여부OUTSIDE_OPERATING_HOURS
6-1triggeredAt이 미래가 아닌지TRIGGERED_IN_FUTURE
6-2endTime이 미래인지RECORDING_TIME_IN_PAST
6-3triggeredAt이 startTime~endTime 사이TRIGGERED_BEFORE_START / TRIGGERED_AFTER_END
7endTime - startTime === recordingIntervalINTERVAL_MISMATCH
8초상권 동의PORTRAIT_RIGHTS_CONSENT_REQUIRED

왜 UTC → KST 변환이 필요한가?​

운영시간은 KST 기준으로 저장되어 있고, 클라이언트는 UTC로 시간을 보냅니다. 서버가 이 두 시간을 비교하려면 같은 시간대로 맞춰야 합니다.

케이스 1: 시각이 달라지는 경우​

운영시간: 화요일 09:00 ~ 24:00 (KST)
클라이언트 요청: "2026-02-19T00:00:00.000Z"
UTCKST
시각00:0009:00
요일목요일목요일

UTC 00:00은 운영시간 09:00~24:00에 포함되지 않아 검증 실패. 하지만 실제로는 KST 09:00이므로 운영시간 내입니다.

케이스 2: 요일까지 달라지는 경우​

클라이언트 요청: "2026-02-18T15:30:00.000Z"
이 경우가 더 위험합니다

UTC 기준 수요일이지만 KST 기준 목요일. 변환 없이는 수요일 운영시간으로 잘못 검증합니다. 수요일과 목요일의 운영시간이 다를 수 있습니다.

정리: 운영시간이 KST로 정의되어 있으니, 비교 대상인 예약 시간도 KST로 맞춰야 올바른 요일 + 올바른 시각으로 비교할 수 있습니다.

FAQ​

Q: 클라이언트에서 운영시간 자정 넘김 로직을 직접 구현해야 하나요?​

아닙니다. 검증은 서버가 처리합니다. 클라이언트는 UTC 시간만 정확히 보내면 됩니다. 다만 UI에서 예약 가능 시간대를 표시할 때는 openTime > closeTime 조건으로 자정 넘김을 감지하여 다음 날까지 표시해야 합니다.

Q: triggeredAt은 왜 필요한가요?​

사용자가 실제로 예약 버튼을 누른 시점을 기록합니다. 서버는 이 시간이 미래가 아닌지(클라이언트 시계 조작 방지), startTime~endTime 범위 내인지를 검증합니다.

Q: 24:00은 뭔가요? 00:00과 다른가요?​

24:00은 "당일 자정"을 의미합니다. closeTime: "24:00"은 "그날 끝까지"라는 뜻이고, openTime: "00:00"은 "그날 시작부터"라는 뜻입니다. 두 값은 같은 시각이지만 의미가 다릅니다.

Q: fetch-info 없이 바로 reserve를 보내면?​

VALIDATED_GYM_NOT_SET 에러가 발생합니다. 반드시 fetch-info → reserve 순서를 지켜야 합니다.

관련 문서​

변경 이력​

버전날짜변경 내용
v1.0.02026-02-19초기 문서 작성 - 예약 플로우 (fetch-info → reserve) - 운영시간 유형별 가이드 (일반/24시간/자정 넘김) - 서버 검증 8단계 및 에러 코드 - UTC → KST 변환 필요성 설명