---

概述

在 Blue 中，列表是用於組織項目內待辦事項的容器。每個列表可以容納多個待辦事項，並幫助將工作結構化為邏輯組。列表支持定位、鎖定和基於角色的訪問控制。

主要概念

• 每個項目最多可以有 50 個列表
• 列表按位置排序（升序）
• 列表可以鎖定以防止修改
• 列表遵循項目級別和基於角色的權限
• 刪除的列表會移至垃圾桶（軟刪除）

查詢

獲取單個列表

通過 ID 獲取特定的待辦事項列表。

query GetTodoList($id: String!) {
  todoList(id: $id) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    updatedAt
    project {
      id
      name
    }
    createdBy {
      id
      username
    }
  }
}

獲取項目中的所有列表

獲取特定項目的所有待辦事項列表。

query GetProjectLists($projectId: String!) {
  todoLists(projectId: $projectId) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    updatedAt
  }
}

高級列表查詢

使用過濾、排序和分頁查詢列表。

query SearchTodoLists($filter: TodoListsFilterInput!, $sort: [TodoListsSort!], $skip: Int, $take: Int) {
  todoListQueries {
    todoLists(filter: $filter, sort: $sort, skip: $skip, take: $take) {
      items {
        id
        uid
        title
        position
        isDisabled
        isLocked
        createdAt
        updatedAt
        project {
          id
          name
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        total
      }
    }
  }
}

變更

創建列表

在項目中創建一個新的待辦事項列表。

mutation CreateTodoList($input: CreateTodoListInput!) {
  createTodoList(input: $input) {
    id
    uid
    title
    position
    isDisabled
    isLocked
    createdAt
    project {
      id
      name
    }
  }
}

範例：

mutation {
  createTodoList(input: {
    projectId: "project-123"
    title: "Sprint 1 Tasks"
    position: 1.0
  }) {
    id
    title
  }
}

編輯列表

更新現有待辦事項列表的屬性。

mutation EditTodoList($input: EditTodoListInput!) {
  editTodoList(input: $input) {
    id
    title
    position
    isLocked
    updatedAt
  }
}

範例：

mutation {
  editTodoList(input: {
    todoListId: "list-123"
    title: "Sprint 1 - In Progress"
    position: 2.0
    isLocked: true
  }) {
    id
    title
    isLocked
  }
}

刪除列表

刪除待辦事項列表（移至垃圾桶）。

mutation DeleteTodoList($input: DeleteTodoListInput!) {
  deleteTodoList(input: $input) {
    success
  }
}

範例：

mutation {
  deleteTodoList(input: {
    projectId: "project-123"
    todoListId: "list-123"
  }) {
    success
  }
}

標記列表為完成/未完成

將列表中的所有待辦事項標記為完成或未完成。

# Mark as done
mutation MarkListDone($todoListId: String!, $filter: TodosFilter) {
  markTodoListAsDone(todoListId: $todoListId, filter: $filter)
}

# Mark as undone
mutation MarkListUndone($todoListId: String!, $filter: TodosFilter) {
  markTodoListAsUndone(todoListId: $todoListId, filter: $filter)
}

輸入類型

CreateTodoListInput

參數	類型	必需	描述
projectId	String!	✅ 是	將創建列表的項目 ID
title	String!	✅ 是	列表的名稱
position	Float!	✅ 是	列表的位置（用於排序）

EditTodoListInput

參數	類型	必需	描述
todoListId	String!	✅ 是	要編輯的列表 ID
title	String	否	列表的新標題
position	Float	否	列表的新位置
isLocked	Boolean	否	列表是否應鎖定

DeleteTodoListInput

參數	類型	必需	描述
projectId	String!	✅ 是	項目 ID（用於驗證）
todoListId	String!	✅ 是	要刪除的列表 ID

TodoListsFilterInput

參數	類型	必需	描述
companyIds	[String!]!	✅ 是	按公司 ID 過濾
projectIds	[String!]	否	按特定項目 ID 過濾
ids	[String!]	否	按特定列表 ID 過濾
titles	[String!]	否	按列表標題過濾
search	String	否	按標題搜索列表

TodoListsSort 值

值	描述
title_ASC	按標題升序排序
title_DESC	按標題降序排序
createdAt_ASC	按創建日期升序排序
createdAt_DESC	按創建日期降序排序
updatedAt_ASC	按更新日期升序排序
updatedAt_DESC	按更新日期降序排序
position_ASC	按位置升序排序（默認）
position_DESC	按位置降序排序

回應類型

TodoList 類型

欄位	類型	描述
id	ID!	唯一標識符
uid	String!	用戶友好的標識符
position	Float!	列表位置以便排序
title	String!	列表名稱
isDisabled	Boolean!	列表是否被禁用
isLocked	Boolean	列表是否被鎖定
createdAt	DateTime!	創建時間戳
updatedAt	DateTime!	最後更新時間戳
activity	Activity	關聯的活動日誌
createdBy	User	創建列表的用戶
project	Project!	父項目
todos	[Todo!]!	此列表中的待辦事項
todosCount	Int!	待辦事項數量

TodoListsPagination 類型

欄位	類型	描述
items	[TodoList!]!	待辦事項列表數組
pageInfo	PageInfo!	分頁信息

所需權限

查詢權限

操作	所需權限
todoList	Must be authenticated
todoLists	Must be authenticated and in company
todoListQueries.todoLists	Must be authenticated and in company

變更權限

操作	允許的項目級角色
createTodoList	OWNER, ADMIN, MEMBER
editTodoList	OWNER, ADMIN, MEMBER, CLIENT
deleteTodoList	OWNER, ADMIN, MEMBER
markTodoListAsDone	OWNER, ADMIN, MEMBER
markTodoListAsUndone	OWNER, ADMIN, MEMBER

注意： 擁有 CLIENT 角色的用戶可以編輯列表，但不能創建或刪除它們。擁有 VIEW_ONLY 或 COMMENT_ONLY 角色的用戶不能創建、編輯或刪除列表。

錯誤響應

TodoListNotFoundError

{
  "errors": [{
    "message": "Todo list was not found.",
    "extensions": {
      "code": "TODO_LIST_NOT_FOUND"
    }
  }]
}

ProjectNotFoundError

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

最大列表錯誤

{
  "errors": [{
    "message": "You have reached the maximum number of todo lists for this project.",
    "extensions": {
      "code": "INTERNAL_SERVER_ERROR"
    }
  }]
}

未授權錯誤

{
  "errors": [{
    "message": "Unauthorized",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

重要說明

• 列表限制：每個項目最多可以有 50 個列表
• 軟刪除：刪除的列表會移至垃圾桶，並且可以潛在地恢復
• 位置管理：創建列表時，確保位置不衝突。使用增量值（1.0、2.0、3.0）以允許在列表之間插入
• 基於角色的訪問：列表可以通過 ProjectUserRoleTodoList 權限隱藏某些角色
• Webhooks：列表的創建、更新和刪除會觸發 webhook（如果已配置）
• 活動跟踪：所有列表操作都會記錄在活動摘要中
• 實時更新：列表變更通過訂閱發布以實現實時更新

相關操作

• 使用 todos 查詢以獲取列表中的待辦事項
• 使用 createTodo 變更以將待辦事項添加到列表中
• 使用 moveTodo 變更以在列表之間移動待辦事項
• 使用 subscribeToTodoList 訂閱列表變更