用戶管理 API

完整的 API 參考，用於管理 Blue 項目和公司的用戶、邀請、角色和權限

概述

用戶管理 API 提供全面的工具，用於管理團隊成員、控制訪問權限，以及在 Blue 項目和公司中組織您的工作力。無論您是添加新團隊成員、管理現有用戶，還是定義自定義權限結構，這些 API 都能處理用戶生命週期管理的所有方面。

Blue 中的用戶管理運作於兩個層級：

項目層級：管理特定項目內的用戶，並具有項目特定的權限
公司層級：管理整個組織內的用戶，並具有公司範圍的訪問權限

可用操作

核心用戶管理

操作	描述	連結
Invite User	向具有特定訪問級別的新用戶發送邀請	View Details →
List Users	查詢和篩選項目或公司的用戶	View Details →
Remove User	從項目或公司中移除用戶	View Details →

角色和權限管理

操作	描述	連結
Custom Roles	創建和管理具有細粒度權限的自定義角色	View Details →

訪問級別

Blue 提供一個層次化的權限系統，具有預定義的訪問級別：

標準訪問級別

級別	描述	能力
OWNER	完全控制項目/公司	All permissions, can transfer ownership
ADMIN	管理訪問	User management, settings, billing
MEMBER	標準團隊成員	Full project functionality, limited admin access
CLIENT	外部客戶訪問	Limited project visibility, focused on deliverables
COMMENT_ONLY	僅限評論訪問	可以查看和評論，不能編輯
VIEW_ONLY	只讀訪問	Can view content only

權限層次

用戶只能邀請或管理與自己相同級別或以下的用戶：

擁有者可以管理所有訪問級別
管理員可以管理管理員、成員、客戶、僅評論、僅查看
成員可以管理成員、客戶、僅評論、僅查看
客戶只能管理其他客戶

關鍵概念

用戶邀請

基於電子郵件：通過電子郵件地址邀請用戶
角色分配：在邀請時設置訪問級別和可選的自定義角色
多項目：單個邀請可以授予對多個項目的訪問
過期：邀請在 7 天後過期
自動通知：Blue 自動發送電子郵件邀請

項目與公司訪問

項目邀請：僅授予對特定項目的訪問
公司邀請：授予公司級別的訪問，並可選擇包括特定項目
公司擁有者：自動獲得所有公司項目的管理員訪問
範圍限制：無法結合項目和公司邀請參數

自定義角色

細粒度權限：定義超出標準訪問級別的特定能力
項目特定：自定義角色範圍限於單個項目
字段級控制：控制對特定自定義字段的訪問
行為限制：限制特定行為（創建、編輯、刪除等）

常見模式

邀請新團隊成員

mutation InviteTeamMember {
  inviteUser(input: {
    email: "john.doe@company.com"
    projectId: "web-redesign"
    accessLevel: MEMBER
  })
}

創建公司範圍的邀請

mutation InviteToCompany {
  inviteUser(input: {
    email: "manager@company.com"
    companyId: "company_123"
    projectIds: ["project_1", "project_2", "project_3"]
    accessLevel: ADMIN
  })
}

列出項目用戶

query ProjectUsers {
  projectUsers(projectId: "web-redesign") {
    id
    user {
      name
      email
      avatar
    }
    accessLevel
    role {
      name
      permissions
    }
    invitedAt
    joinedAt
  }
}

移除用戶

mutation RemoveProjectUser {
  removeUser(input: {
    userId: "user_456"
    projectId: "web-redesign"
  })
}

創建自定義角色

mutation CreateCustomRole {
  createProjectUserRole(input: {
    projectId: "web-redesign"
    name: "Content Reviewer"
    permissions: {
      canCreateRecords: false
      canEditOwnRecords: true
      canEditAllRecords: false
      canDeleteRecords: false
      canManageUsers: false
      canViewReports: true
    }
  }) {
    id
    name
    permissions
  }
}

權限管理

標準權限矩陣

行為	擁有者	管理員	成員	客戶	僅評論	僅查看
Invite Users	✅ 所有級別	✅ 管理員及以下	✅ 成員及以下	✅ 僅客戶	❌ 否	❌ 否
Remove Users	✅ 所有用戶	✅ 管理員及以下	✅ 成員及以下	✅ 僅客戶	❌ 否	❌ 否
Modify Project Settings	✅ 是	✅ 是	❌ 否	❌ 否	❌ 否	❌ 否
Create Records	✅ 是	✅ 是	✅ 是	✅ 有限	❌ 否	❌ 否
Edit All Records	✅ 是	✅ 是	✅ 是	❌ 否	❌ 否	❌ 否
Delete Records	✅ 是	✅ 是	✅ 是	❌ 否	❌ 否	❌ 否
View Reports	✅ 是	✅ 是	✅ 是	✅ 有限	❌ 否	❌ 否

自定義角色能力

字段級權限：控制對特定自定義字段的訪問
行為特定規則：允許/拒絕特定操作（創建、編輯、刪除）
查看限制：限制用戶可以查看的記錄
功能開關：根據角色啟用/禁用特定功能

最佳實踐

用戶入職

從標準角色開始 - 對大多數用戶使用預定義的訪問級別
逐步權限 - 從有限的訪問開始，根據需要擴展
清晰的溝通 - 在發送邀請時包含上下文
定期審查 - 定期審核用戶訪問

安全考量

最小權限原則 - 授予最低必要的權限
定期訪問審核 - 每季度審查用戶權限
離職流程 - 用戶離開時立即移除訪問
自定義角色文檔 - 記錄自定義角色的目的和限制

團隊組織

一致的命名 - 使用清晰、描述性的角色名稱
角色整合 - 避免創建過多相似的自定義角色
公司結構 - 將權限與組織層級對齊
項目繼承 - 考慮公司角色如何影響項目訪問

錯誤處理

管理用戶時的常見錯誤：

錯誤代碼	描述	解決方案
`USER_ALREADY_IN_THE_PROJECT`	用戶已經擁有項目訪問權限	Check current user list before inviting
`UNAUTHORIZED`	執行操作的權限不足	Verify your access level and permissions
`PROJECT_NOT_FOUND`	項目不存在或無法訪問	Confirm project ID and access rights
`INVITATION_LIMIT`	達到計費層級的邀請限制	Upgrade plan or remove inactive users
`ADD_SELF`	無法邀請自己	使用不同的電子郵件或讓其他管理員邀請您
`COMPANY_BANNED`	公司帳戶已被暫停	Contact support to resolve account status

速率限制

用戶管理操作具有以下速率限制：

邀請：每小時每公司 100 次
用戶查詢：每小時每用戶 1000 次
角色修改：每小時每項目 50 次

概述