---

管理记录分配者

Blue API 提供三种操作来管理记录分配者：设置分配者（智能替换）、添加分配者和移除分配者。这些操作自动处理活动跟踪、通知、Webhook 和实时更新。

设置记录分配者（智能分配）

用新列表替换所有当前分配者。系统智能地计算所需的更改，移除不在新列表中的用户并添加新用户。

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. 触发 Webhook：触发分配者添加/移除的 Webhook
8. 更新图表：标记分析图表以进行刷新
9. 实时更新：向连接的客户端发布更新

简单操作 (添加/移除)

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

重要说明

• 项目成员：分配者应为包含记录的项目的成员
• 无分配限制：每条记录没有最大分配者数量
• 自我分配：用户可以在拥有适当权限的情况下自我分配
• 空数组：向 assigneeIds 提供空数组会从 setTodoAssignees 中移除所有分配者
• 防止重复：系统自动防止重复分配
• 数据库效率：使用连接表 (TodoUser) 以实现可扩展的多对多关系
• 实时更新：所有连接的客户端在分配更改时会立即收到更新

获取可用分配者

要获取可以分配到项目中记录的用户列表：

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

此查询返回所有可以潜在分配到记录的项目成员。

相关操作

• 列出记录 - 获取当前分配者的记录
• 更新记录 - 修改其他记录属性
• 添加评论 - 向分配的记录添加评论