接口名称

角色管理API -（IFeishuTenantV3Role）

功能描述

飞书角色管理接口，用于管理团队成员的专业分工类别，如人事、行政、财务等。一个角色可由一名或多名成员组成。当前接口使用租户令牌访问，适用于租户应用场景。

角色主要用于应用审批场景，管理员可以选择某一角色作为审批人，例如选择财务角色作为报销流程的审批人。这样做可以避免因成员离职变动导致的审批流失效的情况，角色内的其他成员可以继续完成审批，提高审批效率。

参考文档

飞书角色管理API文档

函数列表

函数名称	功能描述	认证方式	HTTP 方法
CreateRoleAsync	创建一个角色	租户令牌	POST
UpdateRoleAsync	修改指定角色的角色名称	租户令牌	PUT
DeleteRoleByIdAsync	删除指定角色	租户令牌	DELETE

函数详细内容

函数名称：创建角色

函数签名：

Task<FeishuApiResult<RoleCreateResult>?> CreateRoleAsync(
    [Body] RoleRequest roleRequest,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
roleRequest	RoleRequest	✅ 必填	创建角色请求体
roleRequest.RoleName	string	✅ 必填	角色名称，在同一租户下角色名称唯一，不能重复创建	"财务角色"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

{
  "code": 0,
  "msg": "success",
  "data": {
    "role_id": "6988772597633617922"
  }
}

常见错误响应：

{
  "code": 400,
  "msg": "角色名称已存在"
}

{
  "code": 403,
  "msg": "无权限创建角色"
}

说明：

• 角色名称在同一租户下必须唯一
• 创建的角色可以用于审批流程配置
• 角色创建后会返回唯一的角色ID

代码示例：

// 创建财务角色用于报销审批流程
async function createFinanceRole() {
  const roleRequest = {
    role_name: "财务角色"
  };

  try {
    const response = await feishuTenantV3Role.createRoleAsync(roleRequest);
    if (response.code === 0) {
      console.log('财务角色创建成功，角色ID:', response.data.role_id);
      
      // 将角色配置到审批流程中
      await configureApprovalProcess(response.data.role_id);
    } else {
      console.error('角色创建失败:', response.msg);
    }
  } catch (error) {
    console.error('创建角色时发生错误:', error);
  }
}

// 配置审批流程
async function configureApprovalProcess(roleId) {
  // 将财务角色设置为报销审批的审批人
  console.log(`角色 ${roleId} 已配置为报销审批流程的审批人`);
}

---

函数名称：修改角色名称

函数签名：

Task<FeishuNullDataApiResult?> UpdateRoleAsync(
  [Path] string role_id,
  [Body] RoleRequest roleRequest,
  CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
role_id	string	✅ 必填	角色 ID	"6988772597633617922"
roleRequest	RoleRequest	✅ 必填	角色更新请求体
roleRequest.RoleName	string	✅ 必填	新的角色名称	"新财务角色"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

{
  "code": 0,
  "msg": "success"
}

常见错误响应：

{
  "code": 404,
  "msg": "角色不存在"
}

{
  "code": 400,
  "msg": "角色名称已存在"
}

说明：

• 只能修改角色名称，不能修改其他属性
• 新的角色名称在同一租户下必须唯一
• 角色名称修改不会影响现有的审批流程配置

代码示例：

// 修改角色名称以适应组织架构调整
async function updateRoleName() {
  const roleId = "6988772597633617922";
  const roleRequest = {
    role_name: "高级财务分析师角色"
  };

  try {
    const response = await feishuTenantV3Role.updateRoleAsync(roleId, roleRequest);
    if (response.code === 0) {
      console.log('角色名称更新成功');
      
      // 通知相关审批系统角色名称变更
      await notifyApprovalSystems(roleId, roleRequest.role_name);
    } else {
      console.error('角色名称更新失败:', response.msg);
    }
  } catch (error) {
    console.error('更新角色名称时发生错误:', error);
  }
}

// 通知审批系统角色名称变更
async function notifyApprovalSystems(roleId, newName) {
  console.log(`角色 ${roleId} 名称已更新为: ${newName}`);
  // 这里可以调用相关系统的通知接口
}

---

函数名称：删除角色

函数签名：

Task<FeishuNullDataApiResult?> DeleteRoleByIdAsync(
  [Path] string role_id,
  CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
role_id	string	✅ 必填	角色 ID	"6988772597633617922"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

{
  "code": 0,
  "msg": "success"
}

常见错误响应：

{
  "code": 404,
  "msg": "角色不存在"
}

{
  "code": 400,
  "msg": "角色正在被审批流程使用，无法删除"
}

说明：

• 删除角色前请确保该角色未被任何审批流程使用
• 角色删除后，角色内的成员关系也会被清除
• 删除操作不可恢复，请谨慎执行

代码示例：

// 安全删除角色（包含前置检查）
async function safeDeleteRole() {
  const roleId = "6988772597633617922";

  try {
    // 先检查角色是否被审批流程使用
    const isInUse = await checkRoleUsage(roleId);
    if (isInUse) {
      console.warn('角色正在被审批流程使用，无法删除');
      return;
    }

    // 执行删除操作
    const response = await feishuTenantV3Role.deleteRoleByIdAsync(roleId);
    if (response.code === 0) {
      console.log('角色删除成功');
      
      // 记录删除日志
      await logRoleDeletion(roleId);
    } else {
      console.error('角色删除失败:', response.msg);
    }
  } catch (error) {
    console.error('删除角色时发生错误:', error);
  }
}

// 检查角色使用情况
async function checkRoleUsage(roleId) {
  // 这里应该调用检查角色是否被使用的接口
  // 返回 true 表示正在使用，false 表示未被使用
  return false; // 示例中假设未被使用
}

// 记录角色删除日志
async function logRoleDeletion(roleId) {
  console.log(`角色 ${roleId} 已被删除，操作时间: ${new Date().toISOString()}`);
  // 这里可以调用日志系统记录删除操作
}