---

邀請用戶

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），只有公司 擁有者 可以邀請用戶。

邀請類型

項目邀請

邀請用戶加入單個項目：

• 使用 projectId 參數
• 不能同時使用 companyId
• 邀請者必須對該項目有訪問權限
• 訪問級別限制適用

公司邀請

邀請用戶加入公司（並可選擇特定項目）：

• 使用 companyId 參數
• 不能同時使用 projectId
• 只有公司 擁有者 可以使用此方法
• 使用 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 錯誤）

相關操作

• 列出用戶 - 查看項目或公司的所有用戶
• 移除用戶 - 從項目中移除用戶
• 自定義角色 - 管理自定義用戶角色