完整的 API 參考，用於管理 Blue 中的專案 - 創建、更新、刪除和查詢專案
概述
專案是 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
- 跨功能
- 客戶成功
- 設計
- 工程
- 一般（默認）
- 人力資源
- IT
- 市場營銷
- 操作
- 個人
- 採購
- 產品
- 銷售
常見模式
創建基本專案
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 |