项目成员

管理项目成员的角色和权限。

源码: apps/backend/src/routes/schedules.ts（成员管理端点与定时任务定义在同一路由文件中）

所有端点都需要认证（combinedAuth），路由挂载在 /projects/:projectId/members 下。

---

GET /projects/:projectId/members

获取项目成员列表及其角色、权限信息，同时返回可添加的候选人（团队中尚未分配项目角色的成员）。

认证方式

JWT Token / API Key（combinedAuth）

权限要求

项目访问权限（团队成员）

请求参数

Path 参数

参数	类型	必填	说明
projectId	string	是	项目 UUID

响应格式

状态码: 200

{
  "members": [
    {
      "user_id": "uuid",
      "display_name": "张三",
      "avatar_url": "https://...",
      "email": null,
      "roles": [
        {
          "id": "role-uuid",
          "code": "admin",
          "name": "管理员",
          "user_role_id": "user-role-uuid"
        }
      ],
      "direct_permissions": [
        {
          "code": "execute",
          "user_permission_id": "user-perm-uuid"
        }
      ]
    }
  ],
  "candidates": [
    {
      "user_id": "uuid",
      "display_name": "李四",
      "avatar_url": "https://...",
      "email": null
    }
  ],
  "canManage": true
}

字段	类型	说明
members	Member[]	项目成员列表（含角色和直接权限）
candidates	Candidate[]	可添加的候选人（团队成员中尚无项目角色/权限的）
canManage	boolean	当前用户是否有管理权限（admin）

错误码

状态码	错误	说明
403	无权访问该项目	非团队成员
404	项目不存在	项目不存在或已删除

---

POST /projects/:projectId/members

添加项目成员（为用户分配角色或直接权限）。

认证方式

JWT Token / API Key（combinedAuth）

权限要求

项目管理员权限（admin）

请求参数

Path 参数

参数	类型	必填	说明
projectId	string	是	项目 UUID

Body 参数

{
  "user_id": "uuid",
  "role_id": "role-uuid",
  "permission_codes": ["execute", "write"]
}

参数	类型	必填	说明
user_id	string	是	目标用户 UUID
role_id	string	否	角色 UUID（需 scope=project）
permission_codes	string[]	否	直接权限码列表（自由人模式）

role_id 和 permission_codes 至少提供一个。

响应格式

状态码: 201

{
  "success": true,
  "assigned": {
    "roles": ["admin"],
    "permissions": ["execute", "write"]
  }
}

字段	类型	说明
assigned.roles	string[]	已分配的角色 code 列表
assigned.permissions	string[]	已分配的权限 code 列表

错误码

状态码	错误	说明
400	user_id 为必填	缺少 user_id
400	需要指定 role_id 或 permission_codes	两者都未提供
400	角色不存在或不适用于项目	role_id 无效或 scope 不是 project
400	用户不是团队成员	目标用户不在项目所属团队中
403	需要项目管理员权限	缺少 admin 权限
404	项目不存在	项目不存在

---

PUT /projects/:projectId/members/:userId

更新项目成员的角色和权限（替换模式：传入新列表替换旧列表）。

认证方式

JWT Token / API Key（combinedAuth）

权限要求

项目管理员权限（admin）

请求参数

Path 参数

参数	类型	必填	说明
projectId	string	是	项目 UUID
userId	string	是	目标用户 UUID

Body 参数

{
  "role_ids": ["role-uuid-1", "role-uuid-2"],
  "permission_codes": ["execute"]
}

参数	类型	必填	说明
role_ids	string[]	否	新的角色 UUID 列表（替换现有角色）
permission_codes	string[]	否	新的权限码列表（替换现有直接权限）

注意：传入 role_ids 或 permission_codes 时，会先软删除该用户在此项目的所有现有角色/权限，再添加新的。

响应格式

状态码: 200

{
  "success": true
}

错误码

状态码	错误	说明
403	需要项目管理员权限	缺少 admin 权限

---

DELETE /projects/:projectId/members/:userId

移除项目成员（软删除该用户在此项目的所有角色和直接权限）。

认证方式

JWT Token / API Key（combinedAuth）

权限要求

项目管理员权限（admin）

请求参数

Path 参数

参数	类型	必填	说明
projectId	string	是	项目 UUID
userId	string	是	目标用户 UUID

响应格式

状态码: 200

{
  "success": true
}

限制

• 不能移除自己（防止管理员误操作）

错误码

状态码	错误	说明
400	不能移除自己的权限	尝试移除自己
403	需要项目管理员权限	缺少 admin 权限