Skip to main content

개요

Article 도메인은 공지사항 및 게시글 관리, 사용자 알림 시스템을 제공합니다. 파일 첨부 기능과 페이지네이션을 지원합니다.

Types

Article

게시글 정보를 나타냅니다.
id
ID!
게시글 ID
subject
String
게시글 제목
content
String
게시글 내용
attachments
[String]
첨부 파일 URL 목록
type
String
게시글 타입 (예: “notice”, “announcement”)
tag
String
게시글 태그
createdAt
Date!
생성 일시

UserNotification

사용자 알림 정보를 나타냅니다.
id
ID!
알림 ID
key
String!
알림 키 (고유 식별자)
summary
String!
알림 요약
description
String
알림 상세 내용
type
String
알림 타입
status
Int
알림 상태 코드
isRead
Boolean
읽음 여부
isPublic
Boolean
공개 알림 여부
userId
ID
대상 사용자 ID
accommodationId
ID
관련 숙박 시설 ID
data
String
추가 데이터 (JSON 형식)
createdAt
Date!
생성 일시
expiresAt
Date
만료 일시
url
String
관련 URL

Queries

getArticles

게시글 목록을 페이지네이션으로 조회합니다.

GraphQL Signature

query GetArticles($first: Int, $after: String) {
  getArticles(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        subject
        content
        attachments
        type
        tag
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

파라미터

first
Int
가져올 게시글 개수
after
String
페이지네이션 커서 (이 커서 이후의 게시글)

응답

edges
[ArticleEdge!]!
게시글 목록
pageInfo
PageInfo!
페이지 정보
totalCount
Int!
전체 게시글 수

예제

query {
  getArticles(first: 10) {
    edges {
      node {
        id
        subject
        content
        type
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

getArticle

특정 게시글의 상세 정보를 조회합니다.

GraphQL Signature

query GetArticle($id: ID!) {
  getArticle(id: $id) {
    id
    subject
    content
    attachments
    type
    tag
    createdAt
  }
}

파라미터

id
ID!
required
게시글 ID

예제

query {
  getArticle(id: "01HQKS9V8X2N3P4Q5R6S7T8U9V") {
    id
    subject
    content
    attachments
    type
    createdAt
  }
}

getMyUserNotifications

현재 로그인한 사용자의 알림 목록을 조회합니다.

GraphQL Signature

query GetMyUserNotifications(
  $first: Int
  $after: ID
  $accommodationId: ID
) {
  getMyUserNotifications(
    first: $first
    after: $after
    accommodationId: $accommodationId
  ) {
    edges {
      cursor
      node {
        id
        key
        summary
        description
        type
        status
        isRead
        isPublic
        userId
        accommodationId
        data
        createdAt
        expiresAt
        url
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

파라미터

first
Int
가져올 알림 개수
after
ID
이 ID 이후의 알림
accommodationId
ID
특정 숙박 시설 관련 알림만 필터링

응답

edges
[UserNotificationEdge!]!
알림 목록
pageInfo
PageInfo!
페이지 정보
totalCount
Int!
전체 알림 수

예제

query {
  getMyUserNotifications(first: 20) {
    edges {
      node {
        id
        key
        summary
        description
        type
        isRead
        createdAt
        url
      }
    }
    totalCount
  }
}
이 API는 인증이 필요하며, 로그인한 사용자의 알림만 조회됩니다.

Mutations

createArticle

새로운 게시글을 생성합니다.

GraphQL Signature

mutation CreateArticle($input: CreateArticleInput!) {
  createArticle(input: $input) {
    id
    subject
    content
    type
    tag
    createdAt
  }
}

파라미터

input.subject
String
게시글 제목
input.content
String
게시글 내용
input.attachments
String
첨부 파일 URL (JSON 배열 문자열)
input.type
String
게시글 타입
input.tag
String
게시글 태그

응답

Article
Article!
생성된 게시글 정보

예제

mutation {
  createArticle(input: {
    subject: "신규 기능 안내"
    content: "새로운 기능이 추가되었습니다."
    type: "announcement"
    tag: "feature"
  }) {
    id
    subject
    createdAt
  }
}

updateArticle

기존 게시글을 수정합니다.

GraphQL Signature

mutation UpdateArticle($input: UpdateArticleInput!) {
  updateArticle(input: $input) {
    id
    subject
    content
    type
    tag
  }
}

파라미터

input.id
ID!
required
수정할 게시글 ID
input.subject
String
새로운 제목
input.content
String
새로운 내용
input.attachments
String
새로운 첨부 파일 URL
input.type
String
새로운 타입
input.tag
String
새로운 태그

응답

Article
Article!
수정된 게시글 정보

deleteArticle

게시글을 삭제합니다.

GraphQL Signature

mutation DeleteArticle($id: ID!) {
  deleteArticle(id: $id)
}

파라미터

id
ID!
required
삭제할 게시글 ID

응답

result
Boolean!
삭제 성공 여부

uploadArticleAttachments

게시글에 파일을 첨부합니다.

GraphQL Signature

mutation UploadArticleAttachments(
  $articleId: ID!
  $files: [Upload!]!
  $persistFiles: [String!]
) {
  uploadArticleAttachments(
    articleId: $articleId
    files: $files
    persistFiles: $persistFiles
  ) {
    id
    attachments
  }
}

파라미터

articleId
ID!
required
파일을 첨부할 게시글 ID
files
[Upload!]!
required
업로드할 파일 목록
persistFiles
[String!]
유지할 기존 파일 URL 목록

응답

Article
Article!
첨부 파일이 업데이트된 게시글 정보
persistFiles를 지정하지 않으면 기존 첨부 파일이 모두 제거됩니다.

publishUserNotification

사용자 알림을 발송합니다.

GraphQL Signature

mutation PublishUserNotification($input: UserNotificationInput!) {
  publishUserNotification(input: $input) {
    id
    key
    summary
    description
    type
    userId
    accommodationId
  }
}

파라미터

input.key
String!
required
알림 고유 키
input.summary
String!
required
알림 요약
input.description
String
알림 상세 내용
input.type
String!
required
알림 타입 (예: “reservation”, “payment”, “system”)
input.status
Int
알림 상태 코드
input.isRead
Boolean
읽음 여부 (기본값: false)
input.isPublic
Boolean
공개 알림 여부
input.userId
ID
특정 사용자에게만 발송 (미지정 시 전체 공지)
input.accommodationId
ID
관련 숙박 시설 ID
input.accommodationAuthorities
[String!]
특정 권한을 가진 직원에게만 발송
input.expiresAt
Date
알림 만료 일시
input.data
String
추가 데이터 (JSON 문자열)
input.url
String
관련 URL

응답

notifications
[UserNotification]!
발송된 알림 목록 (여러 사용자에게 발송된 경우 배열로 반환)

예제

mutation {
  publishUserNotification(input: {
    key: "reservation_confirmed"
    summary: "예약이 확정되었습니다"
    description: "2025-01-20 체크인 예약이 확정되었습니다."
    type: "reservation"
    userId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    url: "/reservations/01HQKS9V8X"
    data: "{\"reservationId\": \"01HQKS9V8X\"}"
  }) {
    id
    key
    summary
    userId
  }
}

deleteUserNotification

사용자 알림을 삭제합니다.

GraphQL Signature

mutation DeleteUserNotification($id: ID!) {
  deleteUserNotification(id: $id)
}

파라미터

id
ID!
required
삭제할 알림 ID

응답

result
Boolean!
삭제 성공 여부

markReadUserNotifications

여러 알림을 읽음 처리합니다.

GraphQL Signature

mutation MarkReadUserNotifications($ids: [ID!]!) {
  markReadUserNotifications(ids: $ids)
}

파라미터

ids
[ID!]!
required
읽음 처리할 알림 ID 목록

응답

count
Int!
읽음 처리된 알림 개수

예제

mutation {
  markReadUserNotifications(ids: [
    "01HQKS9V8X2N3P4Q5R6S7T8U9V",
    "01HQKS9V8Y3N4P5Q6R7S8T9U0W"
  ])
}

사용 흐름

게시글 관리 흐름

  1. 게시글 작성: createArticle로 게시글 생성
  2. 파일 첨부 (선택): uploadArticleAttachments로 파일 업로드
  3. 게시글 수정 (선택): updateArticle로 내용 수정
  4. 게시글 삭제: deleteArticle로 삭제

알림 시스템 흐름

  1. 알림 발송: publishUserNotification으로 알림 생성 및 발송
  2. 알림 조회: 사용자가 getMyUserNotifications로 알림 확인
  3. 읽음 처리: markReadUserNotifications로 알림 읽음 처리
  4. 알림 삭제: deleteUserNotification으로 알림 삭제

알림 타겟팅

특정 사용자에게 발송
publishUserNotification(input: {
  userId: "01HQKS9V8X"
  # ...
})
특정 숙박 시설의 특정 권한 직원에게 발송
publishUserNotification(input: {
  accommodationId: "01HQKS9V8X"
  accommodationAuthorities: ["manager", "admin"]
  # ...
})
전체 공지
publishUserNotification(input: {
  isPublic: true
  # ...
})

관련 API