完整的 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 |