개요
Core 서비스의 객실 도메인은 숙박 시설의 객실 및 객실 타입을 관리하는 API를 제공합니다. 객실 타입(RoomType)은 객실의 분류이며, 객실(Room)은 실제 물리적 객실을 나타냅니다. 객실 상태, 청소 상태, 점유 타임라인, 가격 정보 등을 관리할 수 있습니다.Queries
getSingleRoomType
특정 객실 타입의 상세 정보를 조회합니다.GraphQL Signature
파라미터
ID!
required
조회할 객실 타입 ID
응답
ID!
객실 타입 고유 식별자
String!
객실 타입 이름 (예: “디럭스”, “스위트”)
String
객실 타입 설명
ID!
소속 숙박시설 ID
Int
우선순위 (높을수록 우선)
Int
기본 숙박 인원
Int
최대 숙박 인원
Int
해당 타입의 전체 객실 수
Int
판매 중지된 객실 수
권한
- 로그인 필요
예제
getSingleRoom
특정 객실의 상세 정보를 조회합니다.GraphQL Signature
파라미터
ID!
required
조회할 객실 ID
응답
ID!
객실 고유 식별자
String!
객실 번호/이름 (예: “101호”, “A동 202호”)
ID!
소속 객실 타입 ID
RoomState
객실 상태: -
NOT_USING: 미사용 - USING: 사용중 - LEFT: 퇴실 -
SELECTED: 선택됨 - POWER_DOWN: 전원 차단CleanState
청소 상태: -
CLEAN: 청소 완료 - DIRTY: 청소 필요 - CLEANING: 청소중 -
NEED_CLEANING: 청소 요망 - URGENT_CLEANING: 긴급 청소 필요 - INSPECTION:
점검중 - NEED_INSPECTION: 점검 필요SaleState
판매 상태: -
ALL: 전체 판매 - OTA: OTA 전용 - DISABLED: 판매 중지CalculatedState
계산된 복합 상태 (state, cleanState, 예약 정보를 종합): -
available: 판매
가능 - availableDirty: 판매 가능 (청소 필요) - cleaning: 청소중 -
usingRental: 대실 사용중 - usingStay: 숙박 사용중 - reservedRental: 대실
예약 - reservedStay: 숙박 예약 - expired: 만료됨 - disabled: 판매 중지 -
기타 다양한 상태 조합Reservation
현재 진행중인 예약 정보
Reservation
다음 예정된 예약 정보
[Amenity]
객실 편의시설 목록
권한
- 로그인 필요
예제
getRoomOccupancyTimelines
객실 점유 타임라인을 조회합니다. 특정 기간 동안의 객실 점유 상태를 확인할 수 있습니다.GraphQL Signature
파라미터
ID!
required
숙박시설 ID
RoomOccupancyTimelineFilterInput
필터 옵션: -
roomTypeId: 특정 객실 타입으로 필터링 - roomId: 특정 객실으로
필터링 - sortKey: 정렬 기준 (기본값: startAt) - sortDirection: 정렬 방향
(asc 또는 desc)Int
조회할 항목 수 (기본값: 20)
String
페이지네이션 커서
응답
[Edge]
타임라인 항목 배열
PageInfo
페이지네이션 정보
권한
- 숙박시설 관리 권한 필요
예제
Mutations
createRoomType
새로운 객실 타입을 생성합니다.GraphQL Signature
파라미터
CreateRoomTypeInput!
required
객실 타입 생성 정보
String!
required
객실 타입 이름 (예: “스탠다드”, “디럭스”, “스위트”)
ID!
required
소속 숙박시설 ID
String
객실 타입 설명
Int
우선순위 (높을수록 우선)
Int
기본 숙박 인원
Int
최대 숙박 인원
String
객실 타입 별칭
권한
- 숙박시설 관리자(MANAGER) 권한 필요
- 활성화된 숙박시설만 가능
예제
에러 처리
동일한 이름의 객실 타입이 이미 존재합니다.
활성화되지 않은 숙박시설에는 객실 타입을 생성할 수 없습니다.
updateRoomType
객실 타입 정보를 수정합니다.GraphQL Signature
파라미터
ID!
required
수정할 객실 타입 ID
String
객실 타입 이름
String
객실 타입 설명
Int
우선순위
Int
기본 숙박 인원
Int
최대 숙박 인원
권한
- 숙박시설 관리자(MANAGER) 권한 필요
deleteRoomType
객실 타입을 삭제합니다.GraphQL Signature
파라미터
ID!
required
삭제할 객실 타입 ID
제약사항
- 해당 타입에 속한 객실이 있으면 삭제 불가
- 기본 객실 타입이면서 유일한 타입인 경우 삭제 불가
권한
- 숙박시설 관리자(MANAGER) 권한 필요
에러 처리
해당 객실 타입에 속한 객실이 존재하여 삭제할 수 없습니다.
createRoom
새로운 객실을 생성합니다.GraphQL Signature
파라미터
CreateRoomInput!
required
객실 생성 정보
String!
required
객실 번호/이름 (예: “101호”, “A동 202호”)
ID!
required
소속 숙박시설 ID
ID
소속 객실 타입 ID (미지정시 기본 객실 타입 사용)
RoomState
초기 객실 상태 (기본값:
NOT_USING)SaleState
판매 상태 (기본값:
ALL)Int
정렬 순서
Int
우선순위
String
RCU(Room Control Unit) ID
String
CCU(Central Control Unit) ID
String
암호화 키
[AmenityInput]
편의시설 목록
응답
String
자동 생성된 Mifare 카드 키
권한
- 숙박시설 관리자(MANAGER) 권한 필요
- 활성화된 숙박시설만 가능
예제
에러 처리
동일한 이름의 객실이 이미 존재합니다.
편의시설 이름 또는 아이콘에 허용되지 않는 문자가 포함되어 있습니다.
updateRoom
객실 정보를 수정합니다.GraphQL Signature
파라미터
ID!
required
수정할 객실 ID
String
객실 번호/이름
ID
객실 타입 ID
RoomState
객실 상태
SaleState
판매 상태
CleanState
청소 상태
Int
정렬 순서
Int
우선순위
[AmenityInput]
편의시설 목록
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
updateRooms
여러 객실을 일괄 수정합니다.GraphQL Signature
파라미터
[UpdateRoomInput!]!
required
수정할 객실 정보 배열
권한
- 숙박시설 관리자(MANAGER) 권한 필요
특징
- 일괄 처리를 위해 트랜잭션 사용
- 각 객실별 감사 로그 자동 기록
deleteRoom
객실을 삭제합니다.GraphQL Signature
파라미터
ID!
required
삭제할 객실 ID
권한
- 숙박시설 관리자(MANAGER) 권한 필요
setRoomState
객실 상태를 변경합니다.GraphQL Signature
파라미터
ID!
required
객실 ID
RoomState!
required
변경할 객실 상태: -
NOT_USING: 미사용 - USING: 사용중 - LEFT: 퇴실 -
SELECTED: 선택됨 - POWER_DOWN: 전원 차단권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
예제
setRoomCleanState
객실 청소 상태를 변경합니다.GraphQL Signature
파라미터
ID!
required
객실 ID
CleanState!
required
변경할 청소 상태: -
CLEAN: 청소 완료 - DIRTY: 청소 필요 - CLEANING:
청소중 - NEED_CLEANING: 청소 요망 - URGENT_CLEANING: 긴급 청소 필요 -
INSPECTION: 점검중 - NEED_INSPECTION: 점검 필요권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
setRoomStateByStaff
스태프가 청소 상태를 단계적으로 진행합니다 (DIRTY → CLEANING → CLEAN).GraphQL Signature
파라미터
ID!
required
객실 ID
동작
DIRTY→CLEANING: 청소 시작CLEANING→CLEAN: 청소 완료- 기타 상태에서는 오류 발생
권한
- 숙박시설 메이드(MAID) 이상 권한 필요
assignRoomRequest
예약에 대해 사용 가능한 객실을 자동으로 배정합니다.GraphQL Signature
파라미터
ID!
required
배정할 객실 타입 ID
String!
required
객실 선택 방식: -
priority: 우선순위 높은 객실 우선 - random: 무작위 선택updatedAt: 가장 오래 업데이트되지 않은 객실 우선
String
예약 타입 (
rental 또는 stay)DateTime!
required
사용 시작 일시
DateTime!
required
사용 종료 일시
ID!
required
예약 ID
배정 조건
- 객실 상태:
NOT_USING - 청소 상태:
CLEAN - 판매 상태:
ALL또는 예약 타입에 맞는 상태 - 카드 상태:
guest가 아님 - 해당 기간에 다른 예약 없음
권한
- 관리자(ADMIN) 권한 필요
예제
에러 처리
배정 가능한 객실이 없습니다.
유효하지 않은 orderBy 값입니다.
createRoomOccupancyTimeline
객실 점유 타임라인을 생성합니다. 특정 기간 동안 객실의 점유 상태를 기록합니다.GraphQL Signature
파라미터
ID!
required
객실 ID
OccupancyStatus!
required
점유 상태: -
OCCUPIED: 점유됨 - DISABLED: 사용 중지DateTime!
required
시작 일시
DateTime!
required
종료 일시
String
메모
Boolean
재고 수량 포함 여부
ID
연관된 예약 ID
제약사항
endAt은startAt보다 이후여야 함- 동일 기간에 동일 상태의 타임라인 중복 불가
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
예제
에러 처리
종료 일시가 시작 일시보다 이전입니다.
동일 기간에 중복된 타임라인이 존재합니다.
updateRoomOccupancyTimeline
객실 점유 타임라인을 수정합니다.GraphQL Signature
파라미터
ID!
required
타임라인 ID
DateTime
시작 일시
DateTime
종료 일시
String
메모
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
deleteRoomOccupancyTimeline
객실 점유 타임라인을 삭제합니다.GraphQL Signature
파라미터
ID!
required
삭제할 타임라인 ID
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
createPrice
객실 타입의 가격 정보를 생성합니다.GraphQL Signature
파라미터
ID!
required
객실 타입 ID
String!
required
가격 타입 (예:
rental, stay)[PriceTimeInput]
시간대별 가격 정보: -
startTime: 시작 시간 - endTime: 종료 시간 - price:
가격 - type: 타입ID
연관된 ARI 패키지 ID
제약사항
- 동일한 타입의 시간대가 겹치면 안 됨
- 동일한
priceType및ariPackageId조합 중복 불가
권한
- 숙박시설 관리자(MANAGER) 권한 필요
에러 처리
시간대가 겹치는 가격 정보가 있습니다.
동일한 가격 정보가 이미 존재합니다.
updatePrice
가격 정보를 수정합니다.GraphQL Signature
파라미터
ID!
required
수정할 가격 ID
String
가격 타입
[PriceTimeInput]
시간대별 가격 정보
권한
- 숙박시설 관리자(MANAGER) 권한 필요
deletePrice
가격 정보를 삭제합니다.GraphQL Signature
파라미터
ID!
required
삭제할 가격 ID
권한
- 숙박시설 관리자(MANAGER) 권한 필요
Room Memo 관리
createRoomMemo
객실 메모를 생성합니다.updateRoomMemo
객실 메모를 수정합니다.setRoomMemo
객실 메모를 생성하거나 수정합니다 (upsert).deleteRoomMemo
객실 메모를 삭제합니다.Room Device 관리
createRoomDevice
객실 디바이스를 생성합니다.updateRoomDevice
객실 디바이스를 수정합니다.bulkUpdateRoomDevice
여러 객실 디바이스를 일괄 수정합니다.deleteRoomDevice
객실 디바이스를 삭제합니다.객실 상태 흐름
기본 객실 상태 (RoomState)
청소 상태 (CleanState)
복합 상태 (CalculatedState)
calculatedState는 다음 정보를 종합하여 계산됩니다:
- 객실 상태 (
state) - 청소 상태 (
cleanState) - 카드 상태 (
cardState) - 예약 정보 (
currentReservation,upcomingReservation) - 점유 타임라인 (
roomOccupancyTimeline)
주요 복합 상태
available: 판매 가능 (청소 완료, 사용 가능)availableDirty: 판매 가능하나 청소 필요cleaning: 청소중needCleaning: 청소 필요urgentCleaning: 긴급 청소 필요inspection: 점검중needInspection: 점검 필요usingRental: 대실 사용중usingStay: 숙박 사용중leftRental: 대실 퇴실leftStay: 숙박 퇴실reservedRental: 대실 예약reservedStay: 숙박 예약expired: 예약 만료expiredEst: 예약 만료 추정usingExpired: 사용중 (예약 만료)usingUnknown: 사용중 (예약 정보 없음)disabled: 판매 중지disabledSuspicious: 판매 중지 (카드 감지됨)powerDown: 전원 차단selected: 선택됨unknown: 알 수 없음
객실 타임라인
OccupancyStatus
객실 점유 타임라인의 상태:OCCUPIED: 예약으로 인한 점유DISABLED: 관리자가 설정한 사용 중지 기간
타임라인 사용 사례
- 예약 점유: 예약 생성 시 자동으로
OCCUPIED타임라인 생성 - 판매 중지: 보수 공사, 시설 점검 등으로
DISABLED타임라인 생성 - 재고 관리:
isIncludedToQuantity플래그로 판매 재고 수량 제어