프로젝트 API

Blue에서 프로젝트를 관리하기 위한 완전한 API 참조 - 프로젝트 생성, 업데이트, 삭제 및 쿼리

개요

프로젝트는 Blue의 핵심 조직 단위입니다. 프로젝트는 목록, 할 일, 사용자 정의 필드, 자동화 및 모든 작업 관련 데이터를 포함합니다. 프로젝트는 회사에 속하며 자체 권한 시스템, 템플릿 및 구성을 가지고 있습니다.

사용 가능한 작업

핵심 프로젝트 작업

작업	설명	링크
Create Project	새 프로젝트 또는 템플릿에서 프로젝트 생성	View Details →
List Projects	프로젝트 쿼리 및 필터링	View Details →
Delete Project	프로젝트를 영구적으로 삭제	View Details →
Archive Project	프로젝트 아카이브/아카이브 해제	View Details →
Rename Project	프로젝트 이름 및 슬러그 업데이트	View Details →
Copy Project	기존 프로젝트 복제	View Details →

프로젝트 구성 요소

구성 요소	설명	링크
Lists	프로젝트 내 할 일 목록 관리	View Details →
Templates	프로젝트 템플릿 작업	View Details →
Activity	프로젝트 활동 및 변경 사항 추적	View Details →

주요 개념

프로젝트 구조

프로젝트는 회사에 속합니다.
각 프로젝트는 여러 목록을 가질 수 있습니다.
목록은 할 일을 포함합니다.
프로젝트는 사용자 정의 필드, 태그 및 자동화를 지원합니다.

권한 모델

프로젝트는 다단계 권한 시스템을 가지고 있습니다:

수준	권한
OWNER	Full control, can delete project
ADMIN	Manage project settings, users, and content
MEMBER	Create and edit content
CLIENT	Limited edit access
VIEW_ONLY	Read-only access
COMMENT_ONLY	Can only comment

프로젝트 카테고리

프로젝트는 더 나은 조직을 위해 분류할 수 있습니다:

CRM
CROSS_FUNCTIONAL
CUSTOMER_SUCCESS
DESIGN
ENGINEERING
GENERAL (기본값)
HR
IT
MARKETING
OPERATIONS
PERSONAL
PROCUREMENT
PRODUCT
SALES

일반 패턴

기본 프로젝트 생성

mutation CreateProject {
  createProject(input: {
    name: "Q1 Marketing Campaign"
    companyId: "company-123"
    category: MARKETING
  }) {
    id
    name
    slug
  }
}

필터로 프로젝트 쿼리

query GetProjects {
  projectList(
    filter: {
      companyIds: ["company-123"]
      isArchived: false
      categories: [MARKETING, SALES]
    }
    sort: [{ field: updatedAt, direction: DESC }]
    take: 20
  ) {
    items {
      id
      name
      category
      todosCount
      todosDoneCount
    }
    pageInfo {
      hasNextPage
      total
    }
  }
}

참고: projectList 쿼리는 프로젝트를 쿼리하는 데 권장되는 접근 방식입니다. 레거시 projects 쿼리가 존재하지만 새로운 구현에는 사용하지 않아야 합니다.

프로젝트 목록 관리

# Get all lists in a project
query GetProjectLists {
  todoLists(projectId: "project-123") {
    id
    title
    position
    todosCount
  }
}

# Create a new list
mutation CreateList {
  createTodoList(input: {
    projectId: "project-123"
    title: "To Do"
    position: 1.0
  }) {
    id
    title
  }
}

모범 사례

프로젝트 명명
- 명확하고 설명적인 이름 사용
- 슬러그에 영향을 줄 수 있는 특수 문자 피하기
- 이름은 50자 이하로 유지
권한 관리
- 최소 권한으로 시작
- 외부 이해관계자에게 CLIENT 역할 사용
- 정기적으로 프로젝트 접근 권한 감사
조직
- 유사한 프로젝트를 그룹화하기 위해 카테고리 사용
- 삭제하는 대신 완료된 프로젝트 아카이브
- 반복적인 프로젝트 유형에 템플릿 사용
성능
- 대규모 프로젝트 목록에 대해 페이지 매김 사용
- 활성/아카이브 상태로 필터링
- 프로젝트당 목록 수 제한 (최대 50)

오류 처리

발생할 수 있는 일반적인 오류:

오류 코드	설명	해결책
`PROJECT_NOT_FOUND`	프로젝트가 존재하지 않거나 접근 권한 없음	Verify project ID and permissions
`COMPANY_NOT_FOUND`	회사가 존재하지 않음	Check company ID
`FORBIDDEN`	권한 부족	Ensure proper role level
`BAD_USER_INPUT`	유효성 검사 오류 (예: 이름이 너무 길음)	Check input validation requirements

개요