Skip to main content

​
개요

Core 서비스의 재고 관리 도메인은 객실 타입별 일별 재고 현황을 관리합니다. 재고 조회, 가용성 확인, 변경 이력 추적 기능을 제공하여 예약 가능한 객실 수를 실시간으로 파악할 수 있습니다.

​
재고 구성 요소

재고는 다음과 같이 구성됩니다:
  • totalCount: 전체 객실 수
  • usageCount: 사용 중인 객실 수 (확정 예약)
  • holdingCount: 임시 보류 객실 수 (예약 진행 중)
  • blockedCount: 차단된 객실 수 (판매 중지)
  • maintenanceCount: 유지보수 중인 객실 수
  • availableCount: 가용 객실 수 (자동 계산)

​
가용 객실 계산

availableCount = totalCount - usageCount - holdingCount - blockedCount - maintenanceCount

​
Types

​
RoomTypeDailyInventory

특정 객실 타입의 일별 재고 정보
​
id
ID!
재고 고유 식별자
​
accommodationId
ID!
숙소 ID
​
roomTypeId
ID!
객실 타입 ID
​
date
String!
대상 날짜 (YYYY-MM-DD 형식)
​
totalCount
Int!
전체 객실 수
​
usageCount
Int!
사용 중인 객실 수
​
holdingCount
Int!
임시 보류 객실 수
​
blockedCount
Int!
차단된 객실 수
​
maintenanceCount
Int!
유지보수 중인 객실 수
​
availableCount
Int!
가용 객실 수 (계산된 필드)
​
version
Int!
낙관적 락을 위한 버전 번호
​
roomType
RoomType
연관된 객실 타입 정보

​
RoomTypeDailyInventoryHistory

재고 변경 이력
​
id
ID!
이력 고유 식별자
​
inventoryId
ID!
재고 ID
​
action
InventoryAction!
재고 변경 액션: CREATE, USE, RELEASE, HOLD, UNHOLD, BLOCK, UNBLOCK, MAINTENANCE, ADJUST
​
previousState
InventoryState!
변경 전 재고 상태
​
newState
InventoryState!
변경 후 재고 상태
​
delta
InventoryState!
변경 차이값
​
referenceType
InventoryReferenceType
참조 타입: RESERVATION, BLOCK, MAINTENANCE, MANUAL
​
referenceId
ID
참조 ID (예약 ID, 차단 ID 등)
​
performedBy
String!
변경 수행자
​
reason
String
변경 사유
​
metadata
JSON
추가 메타데이터

​
InventoryState

재고 상태 정보
​
usageCount
Int!
사용 수량
​
holdingCount
Int!
보류 수량
​
blockedCount
Int!
차단 수량
​
maintenanceCount
Int!
유지보수 수량

​
Queries

​
roomTypeDailyInventory

특정 날짜의 객실 재고를 조회합니다.

​
GraphQL Signature

query RoomTypeDailyInventory(
  $accommodationId: ID!
  $roomTypeId: ID!
  $date: String!
) {
  roomTypeDailyInventory(
    accommodationId: $accommodationId
    roomTypeId: $roomTypeId
    date: $date
  ) {
    id
    date
    totalCount
    usageCount
    holdingCount
    blockedCount
    maintenanceCount
    availableCount
    roomType {
      id
      name
    }
  }
}

​
파라미터

​
accommodationId
ID!
required
숙소 ID
​
roomTypeId
ID!
required
객실 타입 ID
​
date
String!
required
조회할 날짜 (YYYY-MM-DD 형식)

​
응답

​
roomTypeDailyInventory
RoomTypeDailyInventory
해당 날짜의 재고 정보. 재고가 없으면 null 반환

​
예제

query {
  roomTypeDailyInventory(
    accommodationId: "01HQK..."
    roomTypeId: "01HQL..."
    date: "2025-12-25"
  ) {
    id
    date
    totalCount
    availableCount
    roomType {
      name
    }
  }
}

​
roomTypeDailyInventories

날짜 범위의 객실 재고 목록을 조회합니다.

​
GraphQL Signature

query RoomTypeDailyInventories(
  $accommodationId: ID!
  $roomTypeId: ID
  $startDate: String!
  $endDate: String!
) {
  roomTypeDailyInventories(
    accommodationId: $accommodationId
    roomTypeId: $roomTypeId
    startDate: $startDate
    endDate: $endDate
  ) {
    id
    date
    roomTypeId
    totalCount
    availableCount
    roomType {
      id
      name
    }
  }
}

​
파라미터

​
accommodationId
ID!
required
숙소 ID
​
roomTypeId
ID
객실 타입 ID (선택). 미제공 시 모든 객실 타입의 재고 조회
​
startDate
String!
required
시작 날짜 (YYYY-MM-DD 형식, 포함)
​
endDate
String!
required
종료 날짜 (YYYY-MM-DD 형식, 포함)

​
응답

​
roomTypeDailyInventories
[RoomTypeDailyInventory!]!
날짜 범위 내 재고 목록 (날짜 오름차순 정렬)

​
예제

query {
  roomTypeDailyInventories(
    accommodationId: "01HQK..."
    roomTypeId: "01HQL..."
    startDate: "2025-12-25"
    endDate: "2025-12-27"
  ) {
    date
    totalCount
    usageCount
    availableCount
  }
}
재고가 없는 날짜는 결과에 포함되지 않습니다. 재고 데이터는 사전에 생성되어야 합니다.

​
inventoryHistory

재고 변경 이력을 조회합니다.

​
GraphQL Signature

query InventoryHistory($inventoryId: ID!, $limit: Int) {
  inventoryHistory(inventoryId: $inventoryId, limit: $limit) {
    id
    action
    previousState {
      usageCount
      holdingCount
      blockedCount
      maintenanceCount
    }
    newState {
      usageCount
      holdingCount
      blockedCount
      maintenanceCount
    }
    delta {
      usageCount
      holdingCount
      blockedCount
      maintenanceCount
    }
    referenceType
    referenceId
    performedBy
    reason
    createdAt
  }
}

​
파라미터

​
inventoryId
ID!
required
재고 ID
​
limit
Int
조회할 이력 개수 (기본값: 50)

​
응답

​
inventoryHistory
[RoomTypeDailyInventoryHistory!]!
재고 변경 이력 목록 (최신순 정렬)

​
예제

query {
  inventoryHistory(
    inventoryId: "01HQM..."
    limit: 10
  ) {
    action
    previousState {
      usageCount
    }
    newState {
      usageCount
    }
    delta {
      usageCount
    }
    referenceType
    performedBy
    reason
    createdAt
  }
}

​
에러 처리

​
DATA_NOT_FOUND_ON_ID
존재하지 않는 재고 ID입니다.

​
availableInventoryCount

날짜 범위에서 예약 가능한 최소 객실 수를 확인합니다.

​
GraphQL Signature

query AvailableInventoryCount(
  $accommodationId: ID!
  $roomTypeId: ID!
  $startDate: String!
  $endDate: String!
) {
  availableInventoryCount(
    accommodationId: $accommodationId
    roomTypeId: $roomTypeId
    startDate: $startDate
    endDate: $endDate
  )
}

​
파라미터

​
accommodationId
ID!
required
숙소 ID
​
roomTypeId
ID!
required
객실 타입 ID
​
startDate
String!
required
체크인 날짜 (YYYY-MM-DD 형식, 포함)
​
endDate
String!
required
체크아웃 날짜 (YYYY-MM-DD 형식, 포함)

​
응답

​
availableInventoryCount
Int!
날짜 범위 내 최소 가용 재고 수량
  • 재고가 없으면 0 반환
  • 음수는 0으로 처리

​
동작 방식

이 API는 숙박 기간 동안 병목(bottleneck) 날짜를 찾아 예약 가능한 최대 객실 수를 반환합니다. 예시:
  • 12월 25일: 가용 7개
  • 12월 26일: 가용 3개 (병목)
  • 12월 27일: 가용 8개
결과: 3개 (최소값)

​
예제

query {
  availableInventoryCount(
    accommodationId: "01HQK..."
    roomTypeId: "01HQL..."
    startDate: "2025-12-25"
    endDate: "2025-12-27"
  )
}
예약 가능 여부 확인 시 이 API를 사용하세요. 숙박 기간 중 하루라도 재고가 부족하면 예약이 불가능합니다.

​
사용 흐름

​
예약 가능 여부 확인

  1. 가용 재고 조회: availableInventoryCount로 예약 가능한 최대 객실 수 확인
  2. 재고 확인: 요청 객실 수 ≤ 가용 재고 수인지 검증
  3. 예약 진행: 가능하면 예약 프로세스 진행

​
재고 현황 모니터링

  1. 범위 조회: roomTypeDailyInventories로 특정 기간 재고 조회
  2. 상세 확인: 특정 날짜의 상세 정보는 roomTypeDailyInventory로 조회
  3. 이력 추적: inventoryHistory로 재고 변경 이력 확인

​
권한 요구사항

모든 재고 API는 해당 숙소에 대한 관리 권한(isManageableAccommodation)이 필요합니다.

​
관련 API