마일리지 (Mileage)

개요

Core 서비스의 마일리지 도메인은 고객의 마일리지 적립, 사용, 취소 및 마일리지 사용자 관리 기능을 제공합니다. SMS 인증을 통한 마일리지 조회와 결제 연동이 가능하며, 숙소별로 마일리지 설정을 관리할 수 있습니다.

Queries

getAccommodationMileages

숙소의 마일리지 거래 내역을 조회합니다. (관리자 전용)

GraphQL Signature

query GetAccommodationMileages(
  $accommodationId: ID!
  $filter: MileageFilterInput
  $first: Int
  $after: String
) {
  getAccommodationMileages(
    accommodationId: $accommodationId
    filter: $filter
    first: $first
    after: $after
  ) {
    nodes {
      id
      phone
      amount
      paymentType
      isUsed
      isCancelled
      expireAt
      createdAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

파라미터

ID!

required

조회할 숙소 ID (관리 권한 필요)

MileageFilterInput

필터 조건:

keyword: 전화번호 검색 (부분 일치)
paymentType: 결제 유형 필터
dateFrom: 시작 날짜
dateTo: 종료 날짜

Int

페이지당 항목 수 (기본값: 20)

String

페이지네이션 커서

응답

Mileage[]

마일리지 거래 목록

id: 마일리지 거래 고유 ID
phone: 고객 전화번호
amount: 마일리지 금액
paymentType: 결제 유형 (예: “cash”)
isUsed: 사용 여부
isCancelled: 취소 여부
expireAt: 만료일
createdAt: 생성일

PageInfo

페이지네이션 정보

hasNextPage: 다음 페이지 존재 여부
endCursor: 다음 페이지 커서

예제

query {
  getAccommodationMileages(
    accommodationId: "acc_123"
    filter: {
      keyword: "010"
      dateFrom: "2024-01-01"
      dateTo: "2024-12-31"
    }
    first: 10
  ) {
    nodes {
      id
      phone
      amount
      isUsed
      expireAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

{
  "data": {
    "getAccommodationMileages": {
      "nodes": [
        {
          "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
          "phone": "01012345678",
          "amount": 5000,
          "isUsed": false,
          "expireAt": "2025-01-01T00:00:00Z"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      }
    }
  }
}

getAccommodationMileageUsers

숙소의 마일리지 사용자 목록을 조회합니다. (관리자 전용)

GraphQL Signature

query GetAccommodationMileageUsers(
  $accommodationId: ID!
  $filter: MileageUserFilterInput
  $first: Int
  $after: String
) {
  getAccommodationMileageUsers(
    accommodationId: $accommodationId
    filter: $filter
    first: $first
    after: $after
  ) {
    nodes {
      id
      phone
      name
      currentMileage
      totalVisit
      memo
      createdAt
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

파라미터

ID!

required

조회할 숙소 ID (관리 권한 필요)

MileageUserFilterInput

필터 조건:

keyword: 이름 또는 전화번호 검색 (부분 일치)
totalVisit: 최소 방문 횟수
currentMileage: 최소 보유 마일리지

Int

페이지당 항목 수 (기본값: 20)

String

페이지네이션 커서

응답

MileageUser[]

마일리지 사용자 목록

id: 사용자 고유 ID
phone: 전화번호
name: 고객명
currentMileage: 현재 보유 마일리지
totalVisit: 총 방문 횟수
memo: 메모
createdAt: 생성일

예제

query {
  getAccommodationMileageUsers(
    accommodationId: "acc_123"
    filter: {
      keyword: "김"
      currentMileage: 1000
    }
    first: 10
  ) {
    nodes {
      id
      phone
      name
      currentMileage
      totalVisit
    }
  }
}

{
  "data": {
    "getAccommodationMileageUsers": {
      "nodes": [
        {
          "id": "mu_123",
          "phone": "01012345678",
          "name": "김고객",
          "currentMileage": 5000,
          "totalVisit": 3
        }
      ]
    }
  }
}

queryMileage

SMS 인증을 통한 고객 마일리지 조회 API입니다.

GraphQL Signature

query QueryMileage(
  $phone: String!
  $authToken: String!
  $accommodationId: ID!
) {
  queryMileage(
    phone: $phone
    authToken: $authToken
    accommodationId: $accommodationId
  ) {
    phone
    totalAmount
    usedAmount
  }
}

파라미터

String!

required

조회할 전화번호

String!

required

SMS 인증 토큰 (confirmMileageSMSAuth에서 발급)

ID!

required

숙소 ID

응답

String!

조회한 전화번호

Int!

총 적립된 마일리지 (만료되지 않은 마일리지)

Int!

사용된 마일리지

예제

query {
  queryMileage(
    phone: "01012345678"
    authToken: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    accommodationId: "acc_123"
  ) {
    phone
    totalAmount
    usedAmount
  }
}

{
  "data": {
    "queryMileage": {
      "phone": "01012345678",
      "totalAmount": 10000,
      "usedAmount": 5000
    }
  }
}

에러 처리

인증 토큰이 유효하지 않습니다. 다시 SMS 인증을 진행하세요.

인증 토큰은 30분간 유효하며, 만료 시 requestMileageSMSAuth를 통해 재발급 받아야 합니다.

Mutations

setMileageSettings

숙소의 마일리지 설정을 변경합니다. (관리자 전용)

GraphQL Signature

mutation SetMileageSettings(
  $accommodationId: ID!
  $inputs: [MileageSettingInput!]
) {
  setMileageSettings(
    accommodationId: $accommodationId
    inputs: $inputs
  ) {
    key
    value
  }
}

파라미터

ID!

required

설정을 변경할 숙소 ID (관리 권한 필요)

MileageSettingInput[]

설정 항목 배열:

key: 설정 키 (예: “expireAfter”)
value: 설정 값

응답

MileageSetting[]

변경된 설정 목록

key: 설정 키
value: 설정 값

예제

mutation {
  setMileageSettings(
    accommodationId: "acc_123"
    inputs: [
      { key: "expireAfter", value: "365" }
      { key: "minAmount", value: "1000" }
    ]
  ) {
    key
    value
  }
}

{
  "data": {
    "setMileageSettings": [
      { "key": "expireAfter", "value": "365" },
      { "key": "minAmount", "value": "1000" }
    ]
  }
}

addMileage

고객에게 마일리지를 수동으로 적립합니다. (관리자 전용)

GraphQL Signature

mutation AddMileage($input: AddMileageInput!) {
  addMileage(input: $input) {
    id
    phone
    amount
    expireAt
    createdAt
  }
}

파라미터

AddMileageInput!

required

마일리지 적립 정보:

accommodationId (ID!): 숙소 ID
phone (String!): 고객 전화번호
amount (Int!): 적립 금액

응답

Mileage

생성된 마일리지 정보

id: 마일리지 거래 ID
phone: 고객 전화번호
amount: 적립 금액
expireAt: 만료일 (설정된 유효기간 적용)
createdAt: 생성일

예제

mutation {
  addMileage(input: {
    accommodationId: "acc_123"
    phone: "01012345678"
    amount: 5000
  }) {
    id
    phone
    amount
    expireAt
  }
}

{
  "data": {
    "addMileage": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "phone": "01012345678",
      "amount": 5000,
      "expireAt": "2025-12-31T00:00:00Z"
    }
  }
}

전화번호의 하이픈(-)은 자동으로 제거되며, 만료일은 숙소의 마일리지 설정(expireAfter)에 따라 자동 계산됩니다.

cancelMileage

적립된 마일리지를 취소합니다. (관리자 전용)

GraphQL Signature

mutation CancelMileage($id: ID!) {
  cancelMileage(id: $id) {
    id
    isCancelled
  }
}

파라미터

ID!

required

취소할 마일리지 거래 ID

응답

Mileage

취소된 마일리지 정보

id: 마일리지 거래 ID
isCancelled: 취소 여부 (true)

예제

mutation {
  cancelMileage(id: "01HQKS9V8X2N3P4Q5R6S7T8U9V") {
    id
    isCancelled
  }
}

{
  "data": {
    "cancelMileage": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "isCancelled": true
    }
  }
}

에러 처리

해당 ID의 마일리지를 찾을 수 없습니다.

이미 사용된 마일리지는 취소할 수 없습니다.

이미 취소된 마일리지입니다.

updateMileageUser

마일리지 사용자 정보를 수정합니다. (관리자 전용)

GraphQL Signature

mutation UpdateMileageUser($input: UpdateMileageUserInput!) {
  updateMileageUser(input: $input) {
    id
    phone
    name
    memo
  }
}

파라미터

UpdateMileageUserInput!

required

수정할 사용자 정보:

id (ID!): 사용자 ID
accommodationId (ID!): 숙소 ID
phone (String): 전화번호
name (String): 고객명
memo (String): 메모

응답

MileageUser

수정된 사용자 정보

예제

mutation {
  updateMileageUser(input: {
    id: "mu_123"
    accommodationId: "acc_123"
    name: "김고객"
    memo: "VIP 고객"
  }) {
    id
    name
    memo
  }
}

{
  "data": {
    "updateMileageUser": {
      "id": "mu_123",
      "name": "김고객",
      "memo": "VIP 고객"
    }
  }
}

​개요

​Queries

​getAccommodationMileages

​GraphQL Signature

​파라미터

​응답

​예제

​getAccommodationMileageUsers

​GraphQL Signature

​파라미터

​응답

​예제

​queryMileage

​GraphQL Signature

​파라미터

​응답

​예제

​에러 처리

​Mutations

​setMileageSettings

​GraphQL Signature

​파라미터

​응답

​예제

​addMileage

​GraphQL Signature

​파라미터

​응답

​예제

​cancelMileage

​GraphQL Signature

​파라미터

​응답

​예제

​에러 처리

​updateMileageUser

​GraphQL Signature

​파라미터

​응답

​예제

​사용 흐름

​마일리지 조회 흐름 (고객용)

​마일리지 관리 흐름 (관리자용)

​관련 API

개요

Queries

getAccommodationMileages

GraphQL Signature

파라미터

응답

예제

getAccommodationMileageUsers

GraphQL Signature

파라미터

응답

예제

queryMileage

GraphQL Signature

파라미터

응답

예제

에러 처리

Mutations

setMileageSettings

GraphQL Signature

파라미터

응답

예제

addMileage

GraphQL Signature

파라미터

응답

예제

cancelMileage

GraphQL Signature

파라미터

응답

예제

에러 처리

updateMileageUser

GraphQL Signature

파라미터

응답

예제

사용 흐름

마일리지 조회 흐름 (고객용)

마일리지 관리 흐름 (관리자용)

관련 API