---

사용자 목록

Blue는 회사 전체, 프로젝트별 또는 개별 사용자 조회 등 다양한 범위에서 사용자를 나열할 수 있는 여러 쿼리를 제공합니다. 이러한 쿼리는 대규모 사용자 기반을 효율적으로 관리하기 위해 페이지 매김, 필터링 및 정렬을 지원합니다.

기본 예제 - 회사 사용자

회사의 모든 사용자를 나열합니다:

query ListCompanyUsers {
  companyUserList(companyId: "acme-corp") {
    users {
      id
      email
      fullName
      jobTitle
      lastActiveAt
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

고급 예제 - 필터링된 프로젝트 사용자

검색 및 페이지 매김을 통해 프로젝트 사용자를 나열합니다:

query ListProjectUsers {
  projectUserList(
    projectId: "web-redesign"
    search: "engineer"
    first: 20
    orderBy: lastActiveAt_DESC
  ) {
    edges {
      node {
        id
        email
        fullName
        accessLevel
        customRole {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

사용 가능한 쿼리

companyUserList

선택적 필터링과 함께 회사의 모든 사용자를 나열합니다.

입력 매개변수

매개변수	유형	필수	설명
companyId	String!	✅ 예	회사 ID 또는 슬러그
notInProjectId	String	아니오	이미 이 프로젝트에 있는 사용자 제외
search	String	아니오	이름 또는 이메일로 검색
first	Int	아니오	반환할 결과 수 (앞으로 페이지 매김)
after	String	아니오	앞으로 페이지 매김을 위한 커서
last	Int	아니오	반환할 결과 수 (뒤로 페이지 매김)
before	String	아니오	뒤로 페이지 매김을 위한 커서
skip	Int	아니오	건너뛸 결과 수
orderBy	UserOrderByInput	아니오	정렬 순서 (아래 참조)

projectUserList

특정 프로젝트의 모든 사용자를 나열합니다.

입력 매개변수

매개변수	유형	필수	설명
projectId	String!	✅ 예	프로젝트 ID 또는 슬러그
search	String	아니오	이름 또는 이메일로 검색
first	Int	아니오	결과 수 (최대: 200)
after	String	아니오	페이지 매김을 위한 커서
orderBy	UserOrderByInput	아니오	정렬 순서

user

ID로 단일 사용자를 검색합니다.

입력 매개변수

매개변수	유형	필수	설명
id	String!	✅ 예	사용자 ID

정렬 옵션

UserOrderByInput 값

값	설명
createdAt_ASC	등록 날짜로 정렬 (오래된 것부터)
createdAt_DESC	등록 날짜로 정렬 (최신 것부터)
lastActiveAt_ASC	마지막 활동으로 정렬 (오래된 것부터)
lastActiveAt_DESC	마지막 활동으로 정렬 (최신 것부터)
firstName_ASC	이름으로 정렬 (A-Z)
firstName_DESC	이름으로 정렬 (Z-A)
lastName_ASC	성으로 정렬 (A-Z)
lastName_DESC	성으로 정렬 (Z-A)
email_ASC	이메일 주소로 정렬 (A-Z)
email_DESC	이메일 주소로 정렬 (Z-A)
username_ASC	사용자 이름으로 정렬 (A-Z)
username_DESC	사용자 이름으로 정렬 (Z-A)
jobTitle_ASC	직함으로 정렬 (A-Z)
jobTitle_DESC	직함으로 정렬 (Z-A)

응답 필드

사용자 객체

필드	유형	설명
id	String!	고유 사용자 식별자
uid	String!	Firebase 인증 UID
username	String!	사용자가 선택한 사용자 이름
email	String!	이메일 주소 (OWNER/ADMIN만 볼 수 있음)
firstName	String	이름
lastName	String	성
fullName	String	이름과 성의 조합
jobTitle	String	직업 제목
phoneNumber	String	연락처 번호
dateOfBirth	DateTime	생년월일
isEmailVerified	Boolean!	이메일 인증 상태
lastActiveAt	DateTime	마지막 활동 타임스탬프
createdAt	DateTime!	계정 생성 날짜
updatedAt	DateTime!	마지막 프로필 업데이트
isOnline	Boolean!	현재 온라인 상태
timezone	String	사용자의 시간대
locale	String	언어 선호도
theme	JSON	UI 테마 선호도
image	Image	프로필 사진 객체

프로젝트 사용자 추가 필드

프로젝트 사용자를 나열할 때 추가 필드가 제공됩니다:

필드	유형	설명
accessLevel	UserAccessLevel!	프로젝트에서 사용자의 역할
customRole	ProjectUserRole	해당하는 경우 사용자 정의 역할 세부정보
joinedAt	DateTime!	사용자가 프로젝트에 참여한 날짜

페이지 매김 정보

필드	유형	설명
totalItems	Int!	총 사용자 수
totalPages	Int	총 페이지 수 (오프셋 페이지 매김용)
page	Int	현재 페이지 번호
perPage	Int	페이지당 항목 수
hasNextPage	Boolean!	추가 결과 사용 가능
hasPreviousPage	Boolean!	이전 결과 사용 가능
startCursor	String	첫 번째 항목 커서
endCursor	String	마지막 항목 커서

필수 권한

쿼리	필수 권한
companyUserList	Any authenticated user in the company
projectUserList	Any project member (including VIEW_ONLY)
user	Any authenticated user

오류 응답

회사 찾을 수 없음

{
  "errors": [{
    "message": "Company not found",
    "extensions": {
      "code": "COMPANY_NOT_FOUND"
    }
  }]
}

프로젝트 찾을 수 없음

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

권한 없는 접근

{
  "errors": [{
    "message": "You don't have access to this resource",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

중요 사항

• 성능: 대규모 사용자 목록에 대해 페이지 매김을 사용하십시오 (요청당 최대 200 사용자)
• 검색: 이름, 성 및 이메일 필드에서 검색합니다
• 이메일 개인 정보 보호: 이메일 주소는 OWNER 또는 ADMIN 접근 수준이 있는 사용자만 볼 수 있습니다
• 온라인 상태: isOnline는 WebSocket 연결을 통해 실시간으로 업데이트됩니다
• 프로필 이미지: 다양한 크기를 위해 image.variants 필드를 사용하십시오
• 필터링: notInProjectId 매개변수는 사용자 선택 인터페이스를 구축할 때 유용합니다
• 접근 수준: 프로젝트 사용자 목록에는 회사 목록에서는 사용할 수 없는 역할 정보가 포함되어 있습니다

관련 작업

• 사용자 관리 개요 - 사용자 관리 작업
• 사용자 제거 - 프로젝트에서 사용자 제거
• 사용자 정의 역할 - 사용자 권한 관리