---

邀请用户

inviteUser 变更允许您邀请用户加入您的 Blue 项目或公司。用户可以被分配预定义的访问级别或具有特定权限的自定义角色。

基本示例

邀请具有标准访问级别的用户：

mutation InviteUserToProject {
  inviteUser(
    input: {
      email: "newuser@example.com"
      projectId: "web-redesign"
      accessLevel: MEMBER
    }
  )
}

高级示例

邀请具有自定义角色的用户加入多个项目：

mutation InviteUserWithCustomRole {
  inviteUser(
    input: {
      email: "contractor@example.com"
      projectIds: ["web-redesign", "mobile-app", "api-v2"]
      accessLevel: MEMBER
      roleId: "role_contractor_123"
    }
  )
}

输入参数

InviteUserInput

参数	类型	必需	描述
email	String!	✅ 是	要邀请的用户的电子邮件地址
accessLevel	UserAccessLevel!	✅ 是	授予的访问级别（见下表）
projectId	String	否	单个项目 ID（与 companyId 互斥）
projectIds	[String!]	否	使用 companyId 时的多个项目 ID
companyId	String	否	公司级邀请的公司 ID（与 projectId 互斥）
roleId	String	否	自定义角色 ID（需要 accessLevel: MEMBER）

UserAccessLevel 值

值	描述
OWNER	对项目/公司的完全控制
ADMIN	管理访问权限，可以管理用户和设置
MEMBER	标准成员访问权限，具有完整功能
CLIENT	外部客户的有限访问权限
COMMENT_ONLY	只能查看和评论记录
VIEW_ONLY	对项目的只读访问权限

响应字段

字段	类型	描述
success	Boolean!	邀请是否成功发送

所需权限

用户必须具有足够的权限才能邀请其他人。权限层级被强制执行：

您的角色	可以邀请
OWNER	✅ 所有访问级别
ADMIN	✅ ADMIN, MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY（不能邀请 OWNER）
MEMBER	✅ MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY（不能邀请 OWNER 或 ADMIN）
CLIENT	✅ 仅 CLIENT
COMMENT_ONLY	❌ 不能邀请
VIEW_ONLY	❌ 不能邀请

注意：对于公司邀请（使用 companyId），只有公司 OWNERS 可以邀请用户。

邀请类型

项目邀请

邀请用户加入单个项目：

• 使用 projectId 参数
• 不能同时使用 companyId
• 邀请者必须对项目有访问权限
• 适用访问级别限制

公司邀请

邀请用户加入公司（并可选择特定项目）：

• 使用 companyId 参数
• 不能同时使用 projectId
• 只有公司 OWNERS 可以使用此方法
• 使用 projectIds 数组指定要包含的项目
• 如果省略 projectIds，用户仅获得公司访问权限

自定义角色

使用自定义角色时：

1. 将 accessLevel 设置为 MEMBER
2. 提供自定义角色的 roleId
3. 用户将继承自定义角色中定义的所有权限
4. 自定义角色是项目特定的

要检索可用的自定义角色，请使用 projectUserRoles 查询。

错误响应

用户已在项目中

{
  "errors": [{
    "message": "User is already in the project.",
    "extensions": {
      "code": "USER_ALREADY_IN_THE_PROJECT"
    }
  }]
}

权限不足

{
  "errors": [{
    "message": "You don't have permission to invite users with this access level",
    "extensions": {
      "code": "UNAUTHORIZED"
    }
  }]
}

项目无效

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

超过邀请限制

{
  "errors": [{
    "message": "Unable to invite more people.",
    "extensions": {
      "code": "INVITATION_LIMIT"
    }
  }]
}

不能邀请自己

{
  "errors": [{
    "message": "You are not allowed to add yourself.",
    "extensions": {
      "code": "ADD_SELF"
    }
  }]
}

无效的自定义角色

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

公司被禁止

{
  "errors": [{
    "message": "Company is banned",
    "extensions": {
      "code": "COMPANY_BANNED"
    }
  }]
}

重要说明

• 电子邮件验证：在发送邀请之前，电子邮件地址会被规范化和验证
• 邀请过期：邀请在 7 天后过期，如果未被接受，必须重新发送
• 自动通知：Blue 会自动向新用户发送邀请电子邮件
• 公司所有者：公司所有者在所有项目中自动获得 ADMIN 访问权限
• 计费影响：添加用户可能会影响您的订阅，特别是如果您有按用户计费的定价
• 活动日志：所有用户邀请都会记录以供审计
• 参数排他性：您必须提供 projectId 或 companyId，而不能同时提供两者
• 公司限制：只有公司所有者可以使用 companyId 参数
• 自我邀请：用户不能邀请自己（会抛出 ADD_SELF 错误）

相关操作

• 列出用户 - 查看项目或公司的所有用户
• 移除用户 - 从项目中移除用户
• 自定义角色 - 管理自定义用户角色