Skip to main content

​
개요

ARI Period는 시간 기반 규칙을 정의하여 요금제의 노출 기간이나 요금 조정 적용 기간을 관리합니다. 주기적 반복(REPEAT)과 고정 기간(FIXED) 두 가지 타입을 지원하여 유연한 기간 설정이 가능합니다. 주요 개념:
  • REPEAT 타입: 주기적으로 반복되는 패턴 (예: 매주 금-일, 매월 1일)
  • FIXED 타입: 특정 시작일과 종료일이 있는 고정 기간 (예: 2024-07-01 ~ 2024-08-31)
  • 복합 조건: 요일, 날짜, 월을 조합하여 복잡한 기간 규칙 정의
  • 자동 설명: 시스템이 기간 규칙을 한글로 자동 생성

​
기간 타입

​
REPEAT (주기적 반복)

특정 패턴이 반복되는 기간을 정의합니다. 사용 필드:
  • daysOfWeek: 요일 (0=일요일, 1=월요일, …, 6=토요일)
  • daysOfMonth: 날짜 (1~31)
  • monthsOfYear: 월 (1~12)
  • startDate, endDate: 선택적 (전체 기간의 제약)
예시:
  • 매주 금,토,일: daysOfWeek: [5, 6, 0]
  • 매월 1일, 15일: daysOfMonth: [1, 15]
  • 7~8월의 주말: monthsOfYear: [7, 8], daysOfWeek: [6, 0]

​
FIXED (고정 기간)

시작일과 종료일이 명확한 기간을 정의합니다. 사용 필드:
  • startDate: 시작일 (필수)
  • endDate: 종료일 (필수)
예시:
  • 여름 성수기: startDate: "2024-07-01", endDate: "2024-08-31"
  • 크리스마스 시즌: startDate: "2024-12-20", endDate: "2024-12-26"

​
Queries

​
getAccommodationAriPeriodList

특정 숙박 시설의 모든 기간 목록을 조회합니다.

​
GraphQL Signature

query GetAccommodationAriPeriodList($accommodationId: ID!) {
  getAccommodationAriPeriodList(accommodationId: $accommodationId) {
    id
    accommodationId
    name
    code
    type
    startDate
    endDate
    daysOfWeek
    daysOfMonth
    monthsOfYear
    description
    ranges {
      id
      startDate
      endDate
    }
    createdAt
    updatedAt
  }
}

​
파라미터

​
accommodationId
ID!
required
조회할 숙박 시설 ID

​
응답

​
id
Int!
기간 ID
​
accommodationId
String!
숙박 시설 ID
​
name
String!
기간 이름
​
code
String!
기간 코드 (고유 식별자)
​
type
AriPeriodType!
기간 타입:
  • REPEAT: 주기적 반복
  • FIXED: 고정 기간
​
startDate
Date
시작일 (FIXED 타입 필수, REPEAT 타입 선택)
​
endDate
Date
종료일 (FIXED 타입 필수, REPEAT 타입 선택)
​
daysOfWeek
[Int!]!
적용 요일 배열 (0=일요일, 1=월요일, …, 6=토요일)
​
daysOfMonth
[Int!]!
적용 날짜 배열 (1~31)
​
monthsOfYear
[Int!]!
적용 월 배열 (1~12)
​
description
String!
시스템이 자동 생성한 기간 설명 (한글)
​
ranges
[AriPeriodRange!]!
기간 범위 목록 (향후 확장용)

​
예제

query {
  getAccommodationAriPeriodList(accommodationId: "01H8X9Y2Z3A4B5C6D7E8F9G0H1") {
    id
    name
    code
    type
    startDate
    endDate
    daysOfWeek
    daysOfMonth
    monthsOfYear
    description
  }
}

​
Mutations

​
createAriPeriod

새로운 기간을 생성합니다.

​
GraphQL Signature

mutation CreateAriPeriod($accommodationId: ID!, $input: CreateAriPeriodInput!) {
  createAriPeriod(accommodationId: $accommodationId, input: $input) {
    id
    name
    code
    type
    startDate
    endDate
    daysOfWeek
    daysOfMonth
    monthsOfYear
    description
  }
}

​
파라미터

​
accommodationId
ID!
required
숙박 시설 ID
​
input
CreateAriPeriodInput!
required
기간 생성 정보
​
input.name
String!
required
기간 이름
​
input.code
String!
required
기간 코드 (숙박 시설 내에서 고유해야 함)
​
input.type
AriPeriodType!
required
기간 타입 (REPEAT/FIXED)
​
input.startDate
Date
시작일 (FIXED 타입 필수)
​
input.endDate
Date
종료일 (FIXED 타입 필수)
​
input.daysOfWeek
[Int!]!
required
적용 요일 배열 (빈 배열 가능)
​
input.daysOfMonth
[Int!]!
required
적용 날짜 배열 (빈 배열 가능)
​
input.monthsOfYear
[Int!]!
required
적용 월 배열 (빈 배열 가능)
​
input.ranges
[AriPeriodRangeInput!]!
required
기간 범위 목록 (현재 미사용, 빈 배열 전달)

​
응답

생성된 AriPeriod 객체를 반환합니다.

​
예제

mutation {
  createAriPeriod(
    accommodationId: "01H8X9Y2Z3A4B5C6D7E8F9G0H1"
    input: {
      name: "주말"
      code: "WEEKEND"
      type: REPEAT
      daysOfWeek: [5, 6, 0]
      daysOfMonth: []
      monthsOfYear: []
      ranges: []
    }
  ) {
    id
    name
    type
    daysOfWeek
    description
  }
}

​
검증 규칙

  • 동일한 accommodationId와 code 조합이 이미 존재하면 ARI_PERIOD.CODE_ALREADY_EXISTS 에러 발생
  • FIXED 타입은 startDate와 endDate가 필수
  • description 필드는 서버에서 자동으로 생성됨

​
updateAriPeriod

기존 기간을 수정합니다.

​
GraphQL Signature

mutation UpdateAriPeriod($periodId: Int!, $input: UpdateAriPeriodInput!) {
  updateAriPeriod(periodId: $periodId, input: $input) {
    id
    name
    code
    type
    startDate
    endDate
    daysOfWeek
    daysOfMonth
    monthsOfYear
    description
    updatedAt
  }
}

​
파라미터

​
periodId
Int!
required
수정할 기간 ID
​
input
UpdateAriPeriodInput!
required
수정할 필드 (모든 필드 선택적)

​
예제

mutation {
  updateAriPeriod(
    periodId: 1
    input: {
      name: "주말 및 공휴일"
      daysOfWeek: [5, 6, 0]
    }
  ) {
    id
    name
    daysOfWeek
    description
  }
}

​
검증 규칙

  • 기간 코드 변경 시 중복 검증 실행
  • description 필드는 수정 후 자동으로 재생성됨

​
deleteAriPeriod

기간을 삭제합니다.

​
GraphQL Signature

mutation DeleteAriPeriod($periodId: Int!) {
  deleteAriPeriod(periodId: $periodId)
}

​
파라미터

​
periodId
Int!
required
삭제할 기간 ID

​
응답

​
success
Boolean!
삭제 성공 여부

​
예제

mutation {
  deleteAriPeriod(periodId: 3)
}

​
제약 사항

요금제나 요금 조정에서 사용 중인 기간은 삭제 시 참조 무결성 에러가 발생할 수 있습니다. 사용 중인 기간은 먼저 다른 곳에서 연결을 해제한 후 삭제해야 합니다.

​
기간 설명 자동 생성

시스템은 기간 규칙을 분석하여 한글 설명을 자동으로 생성합니다.

​
REPEAT 타입 설명 패턴

조건생성되는 설명
daysOfWeek: [5, 6, 0]”매주 금요일, 토요일, 일요일”
daysOfMonth: [1, 15]”매월 1일, 15일”
monthsOfYear: [7, 8]”7월, 8월”
monthsOfYear: [6, 7, 8], daysOfWeek: [6, 0]”6월, 7월, 8월의 토요일, 일요일”
위 조건 + startDate, endDate설명 뒤에 “(YYYY년 MM월 DD일 ~ YYYY년 MM월 DD일)” 추가

​
FIXED 타입 설명 패턴

"YYYY년 MM월 DD일 ~ YYYY년 MM월 DD일"

​
예시

# 입력
{
  type: REPEAT
  daysOfWeek: [1, 2, 3, 4]
  monthsOfYear: [3, 4, 5]
  startDate: "2024-03-01"
  endDate: "2024-05-31"
}

# 자동 생성된 description
"3월, 4월, 5월의 월요일, 화요일, 수요일, 목요일 (2024년 3월 1일 ~ 2024년 5월 31일)"

​
활용 사례

​
1. 요금제 노출 기간 설정

요금제의 displayPeriod로 사용하여 특정 기간에만 고객에게 노출: 
mutation {
  createAriRatePlan(
    accommodationId: "01H8X9Y2Z3A4B5C6D7E8F9G0H1"
    input: {
      name: "여름 요금제"
      displayPeriodId: 2  # 여름 성수기 기간
      # ... 기타 필드
    }
  ) {
    id
    displayPeriod {
      name
      description
    }
  }
}

​
2. 요금 조정 적용 기간

특정 기간에만 요금 조정 규칙 적용: 
mutation {
  createAriRate(
    accommodationId: "01H8X9Y2Z3A4B5C6D7E8F9G0H1"
    input: {
      name: "기본 요금"
      # ... 기타 필드
      adjustments: [
        {
          multiplier: "1.3"
          adjustment: "0"
          periodId: 1  # 주말 기간
        }
      ]
    }
  ) {
    id
    adjustments {
      multiplier
      period {
        name
        description
      }
    }
  }
}

​
3. 복잡한 기간 규칙

여러 조건을 조합한 복잡한 기간 정의: 
# 봄 시즌(3-5월) 주말
{
  type: REPEAT
  monthsOfYear: [3, 4, 5]
  daysOfWeek: [6, 0]
}

# 성수기(7-8월) 중 주중
{
  type: REPEAT
  startDate: "2024-07-01"
  endDate: "2024-08-31"
  daysOfWeek: [1, 2, 3, 4, 5]
}

# 매월 마지막 주 금-일
{
  type: REPEAT
  daysOfMonth: [25, 26, 27, 28, 29, 30, 31]
  daysOfWeek: [5, 6, 0]
}

​
사용 흐름

  1. 기간 정의: createAriPeriod로 필요한 기간 규칙 생성
  2. 요금제 연결: 요금제 생성 시 displayPeriodId 설정
  3. 조정 규칙 연결: 요금 생성 시 adjustments[].periodId 설정
  4. 적용 확인: 패키지의 appliedRatePlans로 날짜별 적용 확인
  5. 관리: 필요 시 기간 수정 또는 삭제

​
모범 사례

  1. 명확한 이름: 기간의 목적이 명확히 드러나는 이름 사용
  2. 고유한 코드: 시스템 전체에서 일관성 있는 코드 체계 유지
  3. 단순성 우선: 가능한 한 단순한 규칙으로 기간 정의
  4. 타입 선택: 반복 패턴은 REPEAT, 일회성 기간은 FIXED 사용
  5. 중복 방지: 유사한 기간 규칙 생성 전 기존 기간 재사용 검토

​
관련 API