---

管理記錄指派者

Blue API 提供三種操作來管理記錄指派者：設置指派者（智能替換）、添加指派者和移除指派者。這些操作自動處理活動跟蹤、通知、網絡鉤子和實時更新。

設置記錄指派者（智能指派）

用新的列表替換所有當前的指派者。系統智能地計算所需的變更，移除不在新列表中的用戶並添加新的用戶。

mutation SetRecordAssignees {
  setTodoAssignees(input: {
    todoId: "record_abc123"
    assigneeIds: ["user_123", "user_456", "user_789"]
  }) {
    success
    operationId
  }
}

添加記錄指派者

在不移除現有指派者的情況下添加新的指派者。只有未被指派的用戶會被添加。

mutation AddRecordAssignees {
  addTodoAssignees(input: {
    todoId: "record_abc123"
    assigneeIds: ["user_999", "user_111"]
  }) {
    success
    operationId
  }
}

移除記錄指派者

從記錄中移除特定的指派者。

mutation RemoveRecordAssignees {
  removeTodoAssignees(input: {
    todoId: "record_abc123"
    assigneeIds: ["user_456"]
  }) {
    success
    operationId
  }
}

輸入參數

SetTodoAssigneesInput

參數	類型	必需	描述
todoId	String!	✅ 是	要指派用戶的記錄 ID
assigneeIds	[String!]!	✅ 是	要指派的用戶 ID 陣列（替換所有當前指派者）

AddTodoAssigneesInput

參數	類型	必需	描述
todoId	String!	✅ 是	要指派用戶的記錄 ID
assigneeIds	[String!]!	✅ 是	要添加為指派者的用戶 ID 陣列

RemoveTodoAssigneesInput

參數	類型	必需	描述
todoId	String!	✅ 是	要移除指派者的記錄 ID
assigneeIds	[String!]!	✅ 是	要從指派者中移除的用戶 ID 陣列

回應欄位

欄位	類型	描述
success	Boolean!	操作是否成功完成
operationId	String	用於跟蹤此操作的唯一標識符

所需權限

設置/移除指派者

角色	可以指派/移除
OWNER	✅ 是
ADMIN	✅ 是
MEMBER	✅ 是
CLIENT	✅ 是
VIEW_ONLY	❌ 否
COMMENT_ONLY	❌ 否

添加指派者

角色	可以添加指派者
OWNER	✅ 是
ADMIN	✅ 是
MEMBER	✅ 是
CLIENT	✅ 是
VIEW_ONLY	✅ 是
COMMENT_ONLY	✅ 是

錯誤回應

記錄未找到

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

權限不足

{
  "errors": [{
    "message": "You don't have permission to modify this record",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

輸入無效

{
  "errors": [{
    "message": "Variable '$input' got invalid value; Expected non-nullable type 'String!' not to be null.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

操作比較

特徵	設置指派者	添加指派者	移除指派者
Logic	Smart replacement	Incremental addition	Selective removal
Activity Tracking	✅ 是	❌ 否	❌ 否
通知	✅ 是	❌ 否	❌ 否
Webhooks	✅ 是	❌ 否	❌ 否
Automations	✅ 是	❌ 否	❌ 否
Permission Level	Stricter	More permissive	Stricter

業務邏輯

智能指派 (setTodoAssignees)

當您使用 setTodoAssignees 時，系統：

1. 比較列表：分析當前指派者與新指派者列表
2. 計算變更：確定要移除、保留和添加的用戶
3. 移除用戶：取消指派不在新列表中的用戶
4. 添加用戶：指派新列表中之前未被指派的用戶
5. 跟蹤活動：為每個變更創建活動日誌條目
6. 發送通知：通知新指派的用戶
7. 觸發網絡鉤子：觸發指派者添加/移除的網絡鉤子
8. 更新圖表：標記分析圖表以進行刷新
9. 實時更新：向連接的客戶端發布更新

簡單操作 (添加/移除)

addTodoAssignees 和 removeTodoAssignees 操作提供基本功能，而沒有 setTodoAssignees 的全面跟蹤和通知功能。

重要注意事項

• 項目成員資格：指派者應該是包含該記錄的項目的成員
• 無指派限制：每個記錄沒有最大指派者數量
• 自我指派：如果用戶擁有適當的權限，可以自我指派
• 空陣列：向 setTodoAssignees 提供空的 assigneeIds 陣列會移除所有指派者
• 防止重複：系統自動防止重複指派
• 數據庫效率：使用聯接表 (TodoUser) 以實現可擴展的多對多關係
• 實時更新：所有連接的客戶端在指派變更時會立即收到更新

獲取可用指派者

要獲取可以指派到項目中的記錄的用戶列表：

query GetAssignees {
  assignees(projectId: "project_abc123") {
    id
    name
    email
    avatar
  }
}

此查詢返回所有可以潛在指派到記錄的項目成員。

相關操作

• 列出記錄 - 獲取當前指派者的記錄
• 更新記錄 - 修改其他記錄屬性
• 添加評論 - 向指派的記錄添加評論