接口名称

用户组管理API -（IFeishuTenantV3UserGroup）

功能描述

飞书用户组管理接口，用于管理飞书通讯录中的用户组实体。用户组是飞书通讯录中基础实体之一，在用户组内可添加用户或部门资源。各类业务权限管控可以与用户组关联，从而实现高效便捷的成员权限管控。当前接口使用租户令牌访问，适用于租户应用场景，提供完整的用户组创建、更新、查询、删除等功能。

参考文档

飞书用户组管理API文档

函数列表

函数名称	功能描述	认证方式	HTTP 方法
CreateUserGroupAsync	创建用户组	租户令牌	POST
UpdateUserGroupAsync	更新用户组	租户令牌	PATCH
GetUserGroupInfoByIdAsync	查询指定用户组信息	租户令牌	GET
GetUserGroupsAsync	查询用户组列表	租户令牌	GET
GetUserBelongGroupsAsync	查询指定用户所属的用户组	租户令牌	GET
DeleteUserGroupByIdAsync	删除指定用户组	租户令牌	DELETE

函数详细内容

函数名称：创建用户组

函数签名：

csharp

Task<FeishuApiResult<UserGroupCreateResult>?> CreateUserGroupAsync(
    [Body] UserGroupInfoRequest groupInfoRequest,
    [Query("user_id_type")] string? user_id_type = null,
    [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
groupInfoRequest	UserGroupInfoRequest	✅ 必填	创建用户组请求体	见下方结构
groupInfoRequest.Name	string	✅ 必填	用户组名字，长度不能超过100字符	"项目开发组"
groupInfoRequest.Description	string	⚪ 可选	用户组描述，长度不能超过500字符	"负责项目开发相关工作"
groupInfoRequest.Type	int	⚪ 可选	用户组类型，默认值：1（普通用户组）	1
groupInfoRequest.GroupId	string	⚪ 可选	自定义用户组ID	"custom_dev_group_001"
user_id_type	string	⚪ 可选	用户ID类型	"open_id"
department_id_type	string	⚪ 可选	部门ID类型，默认值：open_department_id	"open_department_id"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "group_id": "grp_1234567890"
  }
}

常见错误响应：

json

{
  "code": 400,
  "msg": "用户组名称重复"
}

json

{
  "code": 403,
  "msg": "无权限创建用户组"
}

说明：

用户组名称在企业内必须唯一
支持自定义用户组ID，便于与外部系统集成
创建的用户组可用于权限管控和成员管理

代码示例：

javascript

// 智能用户组创建系统
class UserGroupCreator {
  constructor() {
    this.groupTemplates = {
      development: {
        name: "开发团队",
        description: "负责产品开发和技术实施"
      },
      design: {
        name: "设计团队", 
        description: "负责产品设计和用户体验"
      },
      marketing: {
        name: "营销团队",
        description: "负责市场推广和品牌建设"
      }
    };
  }

  // 根据业务需求创建用户组
  async createBusinessGroup(businessType, customConfig = {}) {
    try {
      const template = this.groupTemplates[businessType];
      if (!template) {
        throw new Error(`不支持的业务类型: ${businessType}`);
      }

      // 构建用户组请求
      const groupRequest = {
        name: customConfig.name || template.name,
        description: customConfig.description || template.description,
        type: 1, // 普通用户组
        group_id: customConfig.customId || this.generateCustomId(businessType)
      };

      // 验证请求数据
      this.validateGroupRequest(groupRequest);

      showLoadingIndicator('正在创建用户组...');

      const response = await feishuTenantV3UserGroup.createUserGroupAsync(
        groupRequest
      );

      if (response.code === 0) {
        const groupId = response.data.group_id;
        
        console.log(`用户组创建成功: ${groupId}`);
        
        // 创建后进行后续操作
        await this.performPostCreationActions(groupId, groupRequest, businessType);
        
        return {
          success: true,
          groupId: groupId,
          groupInfo: groupRequest
        };
      } else {
        throw new Error(`创建失败: ${response.msg}`);
      }
    } catch (error) {
      console.error('创建用户组时发生错误:', error);
      this.handleCreationError(error, businessType);
      return { success: false, error: error.message };
    } finally {
      hideLoadingIndicator();
    }
  }

  // 生成自定义用户组ID
  generateCustomId(businessType) {
    const timestamp = Date.now();
    const random = Math.random().toString(36).substr(2, 6);
    return `${businessType}_${timestamp}_${random}`;
  }

  // 验证用户组请求
  validateGroupRequest(request) {
    if (!request.name || request.name.trim().length === 0) {
      throw new Error('用户组名称不能为空');
    }

    if (request.name.length > 100) {
      throw new Error('用户组名称长度不能超过100字符');
    }

    if (request.description && request.description.length > 500) {
      throw new Error('用户组描述长度不能超过500字符');
    }

    // 检查名称是否包含特殊字符
    const invalidChars = /[<>'"&]/g;
    if (invalidChars.test(request.name)) {
      throw new Error('用户组名称不能包含特殊字符');
    }
  }

  // 创建后操作
  async performPostCreationActions(groupId, groupRequest, businessType) {
    // 记录创建日志
    await this.logGroupCreation(groupId, groupRequest, businessType);

    // 自动配置权限（如果有预设权限）
    await this.configureDefaultPermissions(groupId, businessType);

    // 发送通知给管理员
    await this.notifyAdministrators(groupId, groupRequest, businessType);

    // 显示成功消息
    this.showCreationSuccess(groupId, groupRequest);
  }

  // 记录用户组创建日志
  async logGroupCreation(groupId, groupRequest, businessType) {
    const logData = {
      groupId,
      groupName: groupRequest.name,
      description: groupRequest.description,
      type: groupRequest.type,
      customId: groupRequest.group_id,
      businessType,
      creator: currentUser.id,
      createdAt: new Date().toISOString()
    };

    console.log('用户组创建日志:', logData);
    
    // 这里可以发送到日志系统
    await this.saveAuditLog(logData);
  }

  // 配置默认权限
  async configureDefaultPermissions(groupId, businessType) {
    const defaultPermissions = this.getDefaultPermissions(businessType);
    
    if (defaultPermissions && defaultPermissions.length > 0) {
      console.log(`为用户组 ${groupId} 配置默认权限...`);
      
      // 这里应该调用权限配置接口
      // await this.assignPermissionsToGroup(groupId, defaultPermissions);
    }
  }

  // 获取默认权限
  getDefaultPermissions(businessType) {
    const permissionMap = {
      development: ['code_read', 'code_write', 'deploy'],
      design: ['design_read', 'design_write', 'prototype'],
      marketing: ['campaign_read', 'campaign_write', 'analytics']
    };
    
    return permissionMap[businessType] || [];
  }

  // 通知管理员
  async notifyAdministrators(groupId, groupRequest, businessType) {
    const notification = {
      title: '新用户组创建通知',
      content: `已创建新的用户组"${groupRequest.name}"，类型：${businessType}`,
      groupId: groupId,
      timestamp: new Date().toISOString()
    };

    // 这里可以发送通知给相关管理员
    console.log('管理员通知:', notification);
  }

  // 显示创建成功消息
  showCreationSuccess(groupId, groupRequest) {
    const successMessage = `
      用户组创建成功！
      <br>
      <strong>名称：</strong>${groupRequest.name}
      <br>
      <strong>ID：</strong>${groupId}
      <br>
      <strong>描述：</strong>${groupRequest.description || '无'}
    `;

    showMessageNotification(successMessage, 'success');
    
    // 更新界面
    this.updateGroupsList();
  }

  // 处理创建错误
  handleCreationError(error, businessType) {
    let userFriendlyMessage = '';

    if (error.message.includes('名称重复')) {
      userFriendlyMessage = '用户组名称已存在，请使用其他名称';
    } else if (error.message.includes('权限')) {
      userFriendlyMessage = '您没有权限创建用户组，请联系管理员';
    } else if (error.message.includes('特殊字符')) {
      userFriendlyMessage = '用户组名称包含不允许的特殊字符';
    } else {
      userFriendlyMessage = `创建用户组失败: ${error.message}`;
    }

    showMessageNotification(userFriendlyMessage, 'error');
  }

  // 保存审计日志
  async saveAuditLog(logData) {
    // 模拟保存到日志系统
    const auditLogs = JSON.parse(localStorage.getItem('auditLogs') || '[]');
    auditLogs.push(logData);
    localStorage.setItem('auditLogs', JSON.stringify(auditLogs));
  }

  // 更新用户组列表界面
  updateGroupsList() {
    // 触发列表刷新
    if (window.userGroupList) {
      window.userGroupList.refresh();
    }
  }
}

// 全局实例
const userGroupCreator = new UserGroupCreator();

// 使用示例
async function createDevelopmentGroup() {
  const customConfig = {
    name: "前端开发团队",
    description: "负责前端页面开发和用户体验优化",
    customId: "frontend_dev_001"
  };

  const result = await userGroupCreator.createBusinessGroup('development', customConfig);
  
  if (result.success) {
    console.log('开发团队创建成功:', result.groupId);
    
    // 可以继续添加成员到该用户组
    await addMembersToGroup(result.groupId, ['user_001', 'user_002']);
  }
}

// 为用户组添加成员
async function addMembersToGroup(groupId, userIds) {
  console.log(`为用户组 ${groupId} 添加成员:`, userIds);
  // 这里应该调用添加用户组成员的接口
}

函数名称：更新用户组

函数签名：

csharp

Task<FeishuNullDataApiResult?> UpdateUserGroupAsync(
   [Path] string group_id,
   [Body] UserGroupUpdateRequest groupUpdateRequest,
   [Query("user_id_type")] string? user_id_type = null,
   [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
group_id	string	✅ 必填	用户组ID	"grp_1234567890"
groupUpdateRequest	UserGroupUpdateRequest	✅ 必填	更新用户组请求体	见下方结构
groupUpdateRequest.Name	string	⚪ 可选	用户组名字，长度不能超过100字符	"新的组名"
groupUpdateRequest.Description	string	⚪ 可选	用户组描述，长度不能超过500字符	"更新后的描述"
user_id_type	string	⚪ 可选	用户ID类型	"open_id"
department_id_type	string	⚪ 可选	部门ID类型，默认值：open_department_id	"open_department_id"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

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

常见错误响应：

json

{
  "code": 404,
  "msg": "用户组不存在"
}

json

{
  "code": 400,
  "msg": "用户组名称重复"
}

说明：

用户组名称在企业内必须唯一
可以单独更新名称或描述，也可以同时更新
空值表示不更新该字段

代码示例：

javascript

// 智能用户组更新系统
class UserGroupUpdater {
  constructor() {
    this.updateHistory = new Map();
    this.validationRules = {
      name: {
        maxLength: 100,
        required: false,
        pattern: /^[^<>'"&]*$/,
        message: '用户组名称不能包含特殊字符且长度不超过100字符'
      },
      description: {
        maxLength: 500,
        required: false,
        message: '用户组描述长度不能超过500字符'
      }
    };
  }

  // 批量更新用户组
  async batchUpdateGroups(updates) {
    const results = [];
    
    for (const update of updates) {
      try {
        const result = await this.updateSingleGroup(update.groupId, update.changes);
        results.push({
          groupId: update.groupId,
          success: true,
          result
        });
      } catch (error) {
        results.push({
          groupId: update.groupId,
          success: false,
          error: error.message
        });
      }
    }

    return results;
  }

  // 更新单个用户组
  async updateSingleGroup(groupId, changes) {
    try {
      // 验证更新数据
      this.validateUpdateData(changes);

      // 检查是否有实际变更
      const hasChanges = Object.keys(changes).some(key => changes[key] !== undefined);
      if (!hasChanges) {
        throw new Error('没有提供任何更新内容');
      }

      // 记录更新前的状态
      const beforeState = await this.getGroupCurrentState(groupId);

      showLoadingIndicator(`正在更新用户组 ${groupId}...`);

      const updateRequest = this.buildUpdateRequest(changes);

      const response = await feishuTenantV3UserGroup.updateUserGroupAsync(
        groupId,
        updateRequest
      );

      if (response.code === 0) {
        // 记录更新操作
        await this.recordUpdateOperation(groupId, changes, beforeState);

        // 通知相关系统
        await this.notifyGroupChange(groupId, changes, 'update');

        console.log(`用户组 ${groupId} 更新成功`);
        
        return { success: true, changes };
      } else {
        throw new Error(`更新失败: ${response.msg}`);
      }
    } catch (error) {
      console.error(`更新用户组 ${groupId} 时发生错误:`, error);
      throw error;
    } finally {
      hideLoadingIndicator();
    }
  }

  // 验证更新数据
  validateUpdateData(changes) {
    for (const [field, value] of Object.entries(changes)) {
      if (value === undefined) continue;

      const rule = this.validationRules[field];
      if (!rule) {
        throw new Error(`不支持的字段: ${field}`);
      }

      if (rule.required && (!value || value.trim().length === 0)) {
        throw new Error(`${field} 不能为空`);
      }

      if (rule.maxLength && value.length > rule.maxLength) {
        throw new Error(`${field} 长度不能超过 ${rule.maxLength} 字符`);
      }

      if (rule.pattern && !rule.pattern.test(value)) {
        throw new Error(rule.message);
      }
    }
  }

  // 获取用户组当前状态
  async getGroupCurrentState(groupId) {
    try {
      const response = await feishuTenantV3UserGroup.getUserGroupInfoByIdAsync(groupId);
      
      if (response.code === 0) {
        return response.data.group;
      } else {
        throw new Error(`获取用户组信息失败: ${response.msg}`);
      }
    } catch (error) {
      console.error('获取用户组当前状态失败:', error);
      return null;
    }
  }

  // 构建更新请求
  buildUpdateRequest(changes) {
    const request = {};
    
    for (const [field, value] of Object.entries(changes)) {
      if (value !== undefined && value !== null) {
        request[field] = value;
      }
    }

    return request;
  }

  // 记录更新操作
  async recordUpdateOperation(groupId, changes, beforeState) {
    const operation = {
      groupId,
      timestamp: new Date().toISOString(),
      operator: currentUser.id,
      changes: changes,
      beforeState: beforeState,
      operationType: 'update'
    };

    // 保存到更新历史
    if (!this.updateHistory.has(groupId)) {
      this.updateHistory.set(groupId, []);
    }
    this.updateHistory.get(groupId).push(operation);

    // 保存到审计日志
    await this.saveAuditLog(operation);

    console.log('用户组更新操作记录:', operation);
  }

  // 通知用户组变更
  async notifyGroupChange(groupId, changes, action) {
    const notification = {
      groupId,
      action,
      changes: changes,
      timestamp: new Date().toISOString(),
      operator: currentUser.name || currentUser.id
    };

    // 这里可以发送通知给相关用户
    console.log('用户组变更通知:', notification);
    
    // 如果用户组关联了权限系统，通知权限系统更新
    if (changes.name) {
      await this.notifyPermissionSystem(groupId, changes.name);
    }
  }

  // 通知权限系统
  async notifyPermissionSystem(groupId, newName) {
    console.log(`通知权限系统用户组 ${groupId} 名称已更改为: ${newName}`);
    // 这里可以调用权限系统的通知接口
  }

  // 保存审计日志
  async saveAuditLog(operation) {
    const auditLogs = JSON.parse(localStorage.getItem('auditLogs') || '[]');
    auditLogs.push(operation);
    localStorage.setItem('auditLogs', JSON.stringify(auditLogs));
  }

  // 获取用户组更新历史
  getUpdateHistory(groupId) {
    return this.updateHistory.get(groupId) || [];
  }

  // 智能名称建议
  suggestGroupName(currentName, context) {
    const suggestions = [];
    
    // 基于当前名称生成变体
    if (currentName.includes('组')) {
      suggestions.push(currentName.replace('组', '团队'));
    }
    
    // 基于上下文添加时间戳
    if (context === 'duplicate') {
      suggestions.push(`${currentName}_${new Date().getFullYear()}`);
      suggestions.push(`${currentName}_v2`);
    }
    
    // 基于业务类型建议
    const businessKeywords = {
      '技术': ['开发', '研发', '工程'],
      '产品': ['产品', '规划', '设计'],
      '运营': ['运营', '市场', '推广']
    };
    
    for (const [keyword, alternatives] of Object.entries(businessKeywords)) {
      if (currentName.includes(keyword)) {
        alternatives.forEach(alt => {
          suggestions.push(currentName.replace(keyword, alt));
        });
      }
    }
    
    return [...new Set(suggestions)].slice(0, 5); // 去重并限制数量
  }
}

// 全局实例
const userGroupUpdater = new UserGroupUpdater();

// 使用示例
async function updateGroupName() {
  const groupId = 'grp_1234567890';
  const newName = '前端开发团队';
  const newDescription = '负责前端页面开发、性能优化和用户体验提升';

  try {
    const result = await userGroupUpdater.updateSingleGroup(groupId, {
      name: newName,
      description: newDescription
    });

    console.log('用户组更新成功:', result);
    
    // 刷新界面
    refreshGroupDetails(groupId);
    
  } catch (error) {
    console.error('更新失败:', error);
    
    // 显示错误并提供名称建议
    const suggestions = userGroupUpdater.suggestGroupName(newName, 'duplicate');
    showNameSuggestions(suggestions);
  }
}

// 显示名称建议
function showNameSuggestions(suggestions) {
  if (suggestions.length === 0) return;

  const suggestionsHtml = suggestions.map(name => 
    `<button class="suggestion-btn" onclick="useSuggestedName('${name}')">${name}</button>`
  ).join('');

  const container = document.createElement('div');
  container.className = 'name-suggestions';
  container.innerHTML = `
    <h4>建议的名称：</h4>
    <div class="suggestions-list">${suggestionsHtml}</div>
  `;

  document.body.appendChild(container);
}

// 使用建议的名称
function useSuggestedName(name) {
  const nameInput = document.getElementById('group-name-input');
  if (nameInput) {
    nameInput.value = name;
  }
  
  // 移除建议面板
  const suggestions = document.querySelector('.name-suggestions');
  if (suggestions) {
    suggestions.remove();
  }
}

// 刷新用户组详情
function refreshGroupDetails(groupId) {
  // 这里应该刷新用户组详情界面
  console.log(`刷新用户组 ${groupId} 的详情`);
}

函数名称：查询指定用户组信息

函数签名：

csharp

Task<FeishuApiResult<UserGroupQueryResult>?> GetUserGroupInfoByIdAsync(
  [Path] string group_id,
  [Query("user_id_type")] string? user_id_type = Consts.User_Id_Type,
  [Query("department_id_type")] string? department_id_type = Consts.Department_Id_Type,
  CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
group_id	string	✅ 必填	用户组ID	"grp_1234567890"
user_id_type	string	⚪ 可选	用户ID类型，默认值：open_id	"open_id"
department_id_type	string	⚪ 可选	部门ID类型，默认值：open_department_id	"open_department_id"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "group": {
      "group_id": "grp_1234567890",
      "name": "项目开发组",
      "description": "负责项目开发相关工作",
      "type": 1,
      "member_count": 15,
      "create_time": "1640995200",
      "update_time": "1641081600"
    }
  }
}

常见错误响应：

json

{
  "code": 404,
  "msg": "用户组不存在"
}

json

{
  "code": 403,
  "msg": "无权限访问该用户组"
}

说明：

返回用户组的详细信息，包括成员数量
支持不同类型的ID查询
包含创建和更新时间信息

代码示例：

javascript

// 用户组详情查看系统
class UserGroupDetailsViewer {
  constructor() {
    this.groupCache = new Map();
    this.detailHistory = new Map();
  }

  // 获取用户组详细信息
  async getGroupDetails(groupId, forceRefresh = false) {
    try {
      // 检查缓存
      if (!forceRefresh && this.groupCache.has(groupId)) {
        const cached = this.groupCache.get(groupId);
        if (Date.now() - cached.timestamp < 5 * 60 * 1000) { // 5分钟缓存
          return cached.data;
        }
      }

      showLoadingIndicator('正在加载用户组详情...');

      const response = await feishuTenantV3UserGroup.getUserGroupInfoByIdAsync(
        groupId
      );

      if (response.code === 0) {
        const groupDetails = response.data.group;
        
        // 缓存数据
        this.groupCache.set(groupId, {
          data: groupDetails,
          timestamp: Date.now()
        });

        // 记录查看历史
        this.recordDetailView(groupId);

        console.log(`获取用户组 ${groupId} 详情成功:`, groupDetails);
        
        return groupDetails;
      } else {
        throw new Error(`获取失败: ${response.msg}`);
      }
    } catch (error) {
      console.error(`获取用户组 ${groupId} 详情失败:`, error);
      this.handleQueryError(error, groupId);
      return null;
    } finally {
      hideLoadingIndicator();
    }
  }

  // 批量获取用户组详情
  async batchGetGroupDetails(groupIds) {
    const results = new Map();
    const toFetch = [];

    // 检查缓存，确定需要请求的用户组
    for (const groupId of groupIds) {
      if (this.groupCache.has(groupId)) {
        const cached = this.groupCache.get(groupId);
        if (Date.now() - cached.timestamp < 5 * 60 * 1000) {
          results.set(groupId, cached.data);
        } else {
          toFetch.push(groupId);
        }
      } else {
        toFetch.push(groupId);
      }
    }

    // 并行请求未缓存的数据
    if (toFetch.length > 0) {
      const fetchPromises = toFetch.map(groupId => 
        this.getGroupDetails(groupId).catch(error => {
          console.error(`批量获取用户组 ${groupId} 失败:`, error);
          return null;
        })
      );

      const fetchResults = await Promise.all(fetchPromises);
      
      fetchResults.forEach((details, index) => {
        const groupId = toFetch[index];
        if (details) {
          results.set(groupId, details);
        }
      });
    }

    return results;
  }

  // 显示用户组详情
  async displayGroupDetails(groupId) {
    const details = await this.getGroupDetails(groupId);
    
    if (!details) {
      showMessageNotification('无法获取用户组详情', 'error');
      return;
    }

    // 构建详情HTML
    const detailsHtml = this.buildDetailsHtml(details);
    
    // 更新界面
    const detailsContainer = document.getElementById('group-details-container');
    if (detailsContainer) {
      detailsContainer.innerHTML = detailsHtml;
      detailsContainer.style.display = 'block';
    }

    // 绑定事件
    this.bindDetailsEvents(groupId);
  }

  // 构建详情HTML
  buildDetailsHtml(details) {
    const createTime = new Date(details.create_time * 1000).toLocaleString();
    const updateTime = new Date(details.update_time * 1000).toLocaleString();
    const typeText = details.type === 1 ? '普通用户组' : '动态用户组';

    return `
      <div class="group-details-card">
        <div class="group-header">
          <h2 class="group-name">${this.escapeHtml(details.name)}</h2>
          <span class="group-type">${typeText}</span>
        </div>
        
        <div class="group-info">
          <div class="info-item">
            <label>用户组ID：</label>
            <span class="group-id">${details.group_id}</span>
            <button class="copy-btn" onclick="copyToClipboard('${details.group_id}')" title="复制ID">📋</button>
          </div>
          
          <div class="info-item">
            <label>描述：</label>
            <span class="group-description">${this.escapeHtml(details.description || '无描述')}</span>
          </div>
          
          <div class="info-item">
            <label>成员数量：</label>
            <span class="member-count">${details.member_count}</span>
            <button class="view-members-btn" onclick="viewGroupMembers('${details.group_id}')">查看成员</button>
          </div>
          
          <div class="info-item">
            <label>创建时间：</label>
            <span class="create-time">${createTime}</span>
          </div>
          
          <div class="info-item">
            <label>更新时间：</label>
            <span class="update-time">${updateTime}</span>
          </div>
        </div>
        
        <div class="group-actions">
          <button class="edit-btn" onclick="editGroup('${details.group_id}')">编辑</button>
          <button class="delete-btn" onclick="deleteGroup('${details.group_id}', '${this.escapeHtml(details.name)}')">删除</button>
          <button class="manage-members-btn" onclick="manageGroupMembers('${details.group_id}')">管理成员</button>
        </div>
        
        <div class="group-stats">
          <h3>统计信息</h3>
          ${this.buildStatsSection(details)}
        </div>
      </div>
    `;
  }

  // 构建统计信息部分
  buildStatsSection(details) {
    return `
      <div class="stats-grid">
        <div class="stat-item">
          <div class="stat-value">${details.member_count}</div>
          <div class="stat-label">成员数量</div>
        </div>
        
        <div class="stat-item">
          <div class="stat-value">${this.calculateGroupAge(details.create_time)}</div>
          <div class="stat-label">创建天数</div>
        </div>
        
        <div class="stat-item">
          <div class="stat-value">${this.getActivityLevel(details.group_id)}</div>
          <div class="stat-label">活跃度</div>
        </div>
      </div>
    `;
  }

  // 计算用户组创建天数
  calculateGroupAge(createTime) {
    const now = Date.now();
    const created = createTime * 1000;
    const days = Math.floor((now - created) / (24 * 60 * 60 * 1000));
    return days;
  }

  // 获取用户组活跃度
  getActivityLevel(groupId) {
    // 这里应该根据实际的活跃度数据计算
    // 简化示例，随机返回活跃度
    const levels = ['高', '中', '低'];
    return levels[Math.floor(Math.random() * levels.length)];
  }

  // 绑定详情页面事件
  bindDetailsEvents(groupId) {
    // 绑定编辑按钮
    const editBtn = document.querySelector('.edit-btn');
    if (editBtn) {
      editBtn.onclick = () => this.editGroup(groupId);
    }

    // 绑定删除按钮
    const deleteBtn = document.querySelector('.delete-btn');
    if (deleteBtn) {
      deleteBtn.onclick = () => this.confirmDeleteGroup(groupId);
    }

    // 绑定成员管理按钮
    const manageMembersBtn = document.querySelector('.manage-members-btn');
    if (manageMembersBtn) {
      manageMembersBtn.onclick = () => this.manageGroupMembers(groupId);
    }
  }

  // 记录查看历史
  recordDetailView(groupId) {
    if (!this.detailHistory.has(groupId)) {
      this.detailHistory.set(groupId, []);
    }

    this.detailHistory.get(groupId).push({
      timestamp: Date.now(),
      viewer: currentUser.id
    });

    // 限制历史记录数量
    const history = this.detailHistory.get(groupId);
    if (history.length > 50) {
      history.splice(0, history.length - 50);
    }
  }

  // 处理查询错误
  handleQueryError(error, groupId) {
    let userFriendlyMessage = '';

    if (error.message.includes('不存在')) {
      userFriendlyMessage = '用户组不存在，可能已被删除';
    } else if (error.message.includes('权限')) {
      userFriendlyMessage = '您没有权限查看该用户组';
    } else {
      userFriendlyMessage = `获取用户组详情失败: ${error.message}`;
    }

    showMessageNotification(userFriendlyMessage, 'error');
  }

  // HTML转义
  escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;
    return div.innerHTML;
  }

  // 清除缓存
  clearCache(groupId = null) {
    if (groupId) {
      this.groupCache.delete(groupId);
    } else {
      this.groupCache.clear();
    }
  }

  // 获取缓存统计
  getCacheStats() {
    return {
      cacheSize: this.groupCache.size,
      oldestEntry: Math.min(...Array.from(this.groupCache.values()).map(item => item.timestamp)),
      newestEntry: Math.max(...Array.from(this.groupCache.values()).map(item => item.timestamp))
    };
  }
}

// 全局实例
const groupDetailsViewer = new UserGroupDetailsViewer();

// 辅助函数
function copyToClipboard(text) {
  navigator.clipboard.writeText(text).then(() => {
    showMessageNotification('ID已复制到剪贴板', 'success');
  }).catch(() => {
    showMessageNotification('复制失败，请手动复制', 'error');
  });
}

function viewGroupMembers(groupId) {
  console.log(`查看用户组 ${groupId} 的成员`);
  // 这里应该跳转到成员管理页面
}

function editGroup(groupId) {
  console.log(`编辑用户组 ${groupId}`);
  // 这里应该打开编辑对话框
}

function deleteGroup(groupId, groupName) {
  console.log(`删除用户组 ${groupId}: ${groupName}`);
  // 这里应该显示删除确认对话框
}

function manageGroupMembers(groupId) {
  console.log(`管理用户组 ${groupId} 的成员`);
  // 这里应该打开成员管理对话框
}

// 使用示例
async function showGroupDetails() {
  const groupId = 'grp_1234567890';
  await groupDetailsViewer.displayGroupDetails(groupId);
}

函数名称：查询用户组列表

函数签名：

csharp

Task<FeishuApiResult<UserGroupListResult>?> GetUserGroupsAsync(
 [Query("page_size")] int? page_size = 10,
 [Query("page_token")] string? page_token = null,
 [Query("type")] int? type = 1,
 CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
page_size	int?	⚪ 可选	分页大小，默认值：10	50
page_token	string	⚪ 可选	分页标记	"xxx"
type	int?	⚪ 可选	用户组类型，默认值：1（普通用户组）	1
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "group_id": "grp_1234567890",
        "name": "项目开发组",
        "description": "负责项目开发相关工作",
        "type": 1,
        "member_count": 15
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

常见错误响应：

json

{
  "code": 403,
  "msg": "无权限查看用户组"
}

说明：

支持分页查询所有用户组
可按类型筛选用户组
返回用户组的基本信息

代码示例：

javascript

// 用户组列表管理系统
class UserGroupListManager {
  constructor() {
    this.allGroups = [];
    this.filteredGroups = [];
    this.currentPage = 1;
    this.pageSize = 20;
    this.hasMore = true;
    this.loading = false;
    this.filters = {
      type: 1,
      name: '',
      memberRange: null
    };
    this.sortBy = 'name';
    this.sortOrder = 'asc';
  }

  // 初始化列表
  async initializeList() {
    try {
      this.showLoadingState();
      await this.loadAllGroups();
      this.renderGroupList();
      this.setupEventListeners();
    } catch (error) {
      console.error('初始化用户组列表失败:', error);
      this.showErrorState(error.message);
    }
  }

  // 加载所有用户组
  async loadAllGroups() {
    this.allGroups = [];
    let pageToken = null;
    
    do {
      const response = await feishuTenantV3UserGroup.getUserGroupsAsync(
        this.pageSize,
        pageToken,
        this.filters.type
      );

      if (response.code === 0) {
        this.allGroups = this.allGroups.concat(response.data.items);
        pageToken = response.data.has_more ? response.data.page_token : null;
        this.hasMore = response.data.has_more;
      } else {
        throw new Error(`加载失败: ${response.msg}`);
      }
    } while (pageToken);

    // 应用当前筛选
    this.applyFilters();
  }

  // 渲染用户组列表
  renderGroupList() {
    const container = document.getElementById('groups-list-container');
    if (!container) return;

    if (this.filteredGroups.length === 0) {
      container.innerHTML = this.getEmptyStateHtml();
      return;
    }

    const groupsHtml = this.filteredGroups
      .map(group => this.buildGroupItemHtml(group))
      .join('');

    container.innerHTML = `
      <div class="groups-list">
        <div class="list-header">
          <div class="header-title">
            <h3>用户组列表</h3>
            <span class="count-badge">共 ${this.filteredGroups.length} 个</span>
          </div>
          <div class="list-actions">
            <button class="create-btn" onclick="createNewGroup()">创建用户组</button>
            <button class="refresh-btn" onclick="refreshList()">刷新</button>
          </div>
        </div>
        <div class="groups-grid">
          ${groupsHtml}
        </div>
        ${this.buildPaginationHtml()}
      </div>
    `;

    this.bindListEvents();
  }

  // 构建用户组项HTML
  buildGroupItemHtml(group) {
    const typeText = group.type === 1 ? '普通用户组' : '动态用户组';
    const typeClass = group.type === 1 ? 'normal' : 'dynamic';
    
    return `
      <div class="group-item" data-group-id="${group.group_id}">
        <div class="group-card">
          <div class="group-header">
            <h4 class="group-name">${this.escapeHtml(group.name)}</h4>
            <span class="group-type ${typeClass}">${typeText}</span>
          </div>
          
          <div class="group-description">
            ${this.escapeHtml(group.description || '暂无描述')}
          </div>
          
          <div class="group-stats">
            <div class="stat-item">
              <span class="stat-icon">👥</span>
              <span class="stat-value">${group.member_count}</span>
              <span class="stat-label">成员</span>
            </div>
          </div>
          
          <div class="group-actions">
            <button class="action-btn view-btn" onclick="viewGroupDetails('${group.group_id}')" title="查看详情">
              👁️
            </button>
            <button class="action-btn edit-btn" onclick="editGroup('${group.group_id}')" title="编辑">
              ✏️
            </button>
            <button class="action-btn members-btn" onclick="manageMembers('${group.group_id}')" title="管理成员">
              👥
            </button>
            <button class="action-btn delete-btn" onclick="deleteGroup('${group.group_id}')" title="删除">
              🗑️
            </button>
          </div>
        </div>
      </div>
    `;
  }

  // 构建分页HTML
  buildPaginationHtml() {
    const totalPages = Math.ceil(this.filteredGroups.length / this.pageSize);
    const currentPage = this.currentPage;
    
    if (totalPages <= 1) return '';

    const pageNumbers = [];
    const startPage = Math.max(1, currentPage - 2);
    const endPage = Math.min(totalPages, currentPage + 2);

    for (let i = startPage; i <= endPage; i++) {
      pageNumbers.push(`
        <button class="page-btn ${i === currentPage ? 'active' : ''}" 
                onclick="goToPage(${i})">${i}</button>
      `);
    }

    return `
      <div class="pagination">
        <button class="page-btn" onclick="goToPage(1)" ${currentPage === 1 ? 'disabled' : ''}>
          ⏮️
        </button>
        <button class="page-btn" onclick="goToPage(${currentPage - 1})" ${currentPage === 1 ? 'disabled' : ''}>
          ⬅️
        </button>
        ${pageNumbers.join('')}
        <button class="page-btn" onclick="goToPage(${currentPage + 1})" ${currentPage === totalPages ? 'disabled' : ''}>
          ➡️
        </button>
        <button class="page-btn" onclick="goToPage(${totalPages})" ${currentPage === totalPages ? 'disabled' : ''}>
          ⏭️
        </button>
      </div>
    `;
  }

  // 应用筛选条件
  applyFilters() {
    let filtered = [...this.allGroups];

    // 按类型筛选
    if (this.filters.type !== null) {
      filtered = filtered.filter(group => group.type === this.filters.type);
    }

    // 按名称筛选
    if (this.filters.name) {
      const nameLower = this.filters.name.toLowerCase();
      filtered = filtered.filter(group => 
        group.name.toLowerCase().includes(nameLower) ||
        (group.description && group.description.toLowerCase().includes(nameLower))
      );
    }

    // 按成员数量范围筛选
    if (this.filters.memberRange) {
      const [min, max] = this.filters.memberRange;
      filtered = filtered.filter(group => 
        group.member_count >= min && 
        (max === null || group.member_count <= max)
      );
    }

    // 排序
    filtered.sort((a, b) => {
      let aVal = a[this.sortBy];
      let bVal = b[this.sortBy];

      if (typeof aVal === 'string') {
        aVal = aVal.toLowerCase();
        bVal = bVal.toLowerCase();
      }

      const result = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
      return this.sortOrder === 'asc' ? result : -result;
    });

    this.filteredGroups = filtered;
  }

  // 设置事件监听器
  setupEventListeners() {
    // 搜索框
    const searchInput = document.getElementById('group-search');
    if (searchInput) {
      searchInput.addEventListener('input', debounce((e) => {
        this.filters.name = e.target.value;
        this.applyFilters();
        this.currentPage = 1;
        this.renderGroupList();
      }, 300));
    }

    // 类型筛选
    const typeFilter = document.getElementById('group-type-filter');
    if (typeFilter) {
      typeFilter.addEventListener('change', (e) => {
        this.filters.type = e.target.value === 'all' ? null : parseInt(e.target.value);
        this.applyFilters();
        this.currentPage = 1;
        this.renderGroupList();
      });
    }

    // 成员数量筛选
    const memberFilter = document.getElementById('member-count-filter');
    if (memberFilter) {
      memberFilter.addEventListener('change', (e) => {
        this.filters.memberRange = e.target.value ? e.target.value.split('-').map(v => parseInt(v)) : null;
        this.applyFilters();
        this.currentPage = 1;
        this.renderGroupList();
      });
    }

    // 排序
    const sortSelect = document.getElementById('sort-select');
    if (sortSelect) {
      sortSelect.addEventListener('change', (e) => {
        const [sortBy, sortOrder] = e.target.value.split('-');
        this.sortBy = sortBy;
        this.sortOrder = sortOrder;
        this.applyFilters();
        this.renderGroupList();
      });
    }
  }

  // 绑定列表事件
  bindListEvents() {
    // 为用户组卡片添加悬停效果
    document.querySelectorAll('.group-item').forEach(item => {
      item.addEventListener('mouseenter', () => {
        item.classList.add('hover');
      });

      item.addEventListener('mouseleave', () => {
        item.classList.remove('hover');
      });
    });
  }

  // 获取空状态HTML
  getEmptyStateHtml() {
    return `
      <div class="empty-state">
        <div class="empty-icon">📁</div>
        <h3>暂无用户组</h3>
        <p>还没有创建任何用户组，点击下方按钮创建第一个用户组</p>
        <button class="primary-btn" onclick="createNewGroup()">创建用户组</button>
      </div>
    `;
  }

  // 显示加载状态
  showLoadingState() {
    const container = document.getElementById('groups-list-container');
    if (container) {
      container.innerHTML = `
        <div class="loading-state">
          <div class="spinner"></div>
          <p>正在加载用户组列表...</p>
        </div>
      `;
    }
  }

  // 显示错误状态
  showErrorState(errorMessage) {
    const container = document.getElementById('groups-list-container');
    if (container) {
      container.innerHTML = `
        <div class="error-state">
          <div class="error-icon">⚠️</div>
          <h3>加载失败</h3>
          <p>${errorMessage}</p>
          <button class="retry-btn" onclick="refreshList()">重试</button>
        </div>
      `;
    }
  }

  // 刷新列表
  async refreshList() {
    await this.initializeList();
    showMessageNotification('用户组列表已刷新', 'success');
  }

  // 获取当前页面数据
  getCurrentPageData() {
    const startIndex = (this.currentPage - 1) * this.pageSize;
    const endIndex = startIndex + this.pageSize;
    return this.filteredGroups.slice(startIndex, endIndex);
  }

  // HTML转义
  escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;
    return div.innerHTML;
  }
}

// 全局实例
const groupListManager = new UserGroupListManager();

// 辅助函数
function createNewGroup() {
  console.log('创建新用户组');
  // 这里应该打开创建用户组对话框
}

function viewGroupDetails(groupId) {
  console.log(`查看用户组详情: ${groupId}`);
  groupDetailsViewer.displayGroupDetails(groupId);
}

function editGroup(groupId) {
  console.log(`编辑用户组: ${groupId}`);
  // 这里应该打开编辑对话框
}

function manageMembers(groupId) {
  console.log(`管理用户组成员: ${groupId}`);
  // 这里应该打开成员管理对话框
}

function deleteGroup(groupId) {
  console.log(`删除用户组: ${groupId}`);
  // 这里应该显示删除确认对话框
}

function goToPage(page) {
  groupListManager.currentPage = page;
  groupListManager.renderGroupList();
}

function refreshList() {
  groupListManager.refreshList();
}

// 防抖函数
function debounce(func, wait) {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
}

// 页面加载完成后初始化
document.addEventListener('DOMContentLoaded', () => {
  groupListManager.initializeList();
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395

函数名称：查询指定用户所属的用户组

函数签名：

csharp

Task<FeishuApiResult<UserBelongGroupListResult>?> GetUserBelongGroupsAsync(
    [Query("member_id")] string member_id,
    [Query("member_id_type")] string? member_id_type = null,
    [Query("group_type")] int? group_type = null,
    [Query("page_size")] int? page_size = 10,
    [Query("page_token")] string? page_token = null,
    [Query("type")] int? type = 1,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
member_id	string	✅ 必填	成员ID	"ou_7d8a6e6df7621556ce0d21922b676706ccs"
member_id_type	string	⚪ 可选	成员ID类型	"open_id"
group_type	int?	⚪ 可选	用户组类型	1
page_size	int?	⚪ 可选	分页大小，默认值：10	50
page_token	string	⚪ 可选	分页标记	"xxx"
type	int?	⚪ 可选	用户组类型，默认值：1	1
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "group_id": "grp_1234567890",
        "name": "项目开发组",
        "description": "负责项目开发相关工作",
        "type": 1
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

常见错误响应：

json

{
  "code": 404,
  "msg": "用户不存在"
}

说明：

用于查询指定用户所属的所有用户组
支持分页查询
可按用户组类型筛选

代码示例：

javascript

// 用户组归属查询系统
class UserGroupMembershipAnalyzer {
  constructor() {
    this.membershipCache = new Map();
    this.groupAnalysisCache = new Map();
  }

  // 获取用户所属的所有用户组
  async getUserGroups(userId, forceRefresh = false) {
    try {
      // 检查缓存
      if (!forceRefresh && this.membershipCache.has(userId)) {
        const cached = this.membershipCache.get(userId);
        if (Date.now() - cached.timestamp < 10 * 60 * 1000) { // 10分钟缓存
          return cached.data;
        }
      }

      showLoadingIndicator(`正在查询用户 ${userId} 的用户组...`);

      const allGroups = [];
      let pageToken = null;

      do {
        const response = await feishuTenantV3UserGroup.getUserBelongGroupsAsync(
          userId,
          null, // member_id_type
          null, // group_type
          100,   // page_size
          pageToken,
          1      // type
        );

        if (response.code === 0) {
          allGroups.push(...response.data.items);
          pageToken = response.data.has_more ? response.data.page_token : null;
        } else {
          throw new Error(`查询失败: ${response.msg}`);
        }
      } while (pageToken);

      // 缓存结果
      this.membershipCache.set(userId, {
        data: allGroups,
        timestamp: Date.now()
      });

      console.log(`用户 ${userId} 所属用户组:`, allGroups);
      
      return allGroups;
    } catch (error) {
      console.error(`查询用户 ${userId} 用户组失败:`, error);
      this.handleMembershipError(error, userId);
      return [];
    } finally {
      hideLoadingIndicator();
    }
  }

  // 分析用户组归属情况
  async analyzeUserMembership(userId) {
    const userGroups = await this.getUserGroups(userId);
    
    if (userGroups.length === 0) {
      return {
        userId,
        groupCount: 0,
        groupTypes: [],
        riskLevel: 'low',
        recommendations: ['建议为用户分配适当的用户组以提高工作效率']
      };
    }

    const analysis = {
      userId,
      groupCount: userGroups.length,
      groups: userGroups,
      groupTypes: this.getUniqueTypes(userGroups),
      riskLevel: this.calculateRiskLevel(userGroups),
      recommendations: []
    };

    // 生成建议
    analysis.recommendations = this.generateRecommendations(analysis);

    return analysis;
  }

  // 获取唯一的用户组类型
  getUniqueTypes(groups) {
    const types = groups.map(group => group.type);
    return [...new Set(types)].map(type => ({
      type,
      name: type === 1 ? '普通用户组' : '动态用户组',
      count: types.filter(t => t === type).length
    }));
  }

  // 计算风险等级
  calculateRiskLevel(groups) {
    if (groups.length === 0) return 'low';
    if (groups.length > 10) return 'high';
    if (groups.length > 5) return 'medium';
    return 'low';
  }

  // 生成建议
  generateRecommendations(analysis) {
    const recommendations = [];

    if (analysis.groupCount === 0) {
      recommendations.push('用户未分配任何用户组，建议根据工作职责分配适当的用户组');
    } else if (analysis.groupCount > 10) {
      recommendations.push('用户所属用户组过多，建议进行权限梳理和优化');
    }

    // 检查权限重叠
    const overlappingGroups = this.findOverlappingGroups(analysis.groups);
    if (overlappingGroups.length > 0) {
      recommendations.push('检测到权限重叠的用户组，建议进行权限优化');
    }

    // 检查关键权限缺失
    const missingPermissions = this.findMissingCriticalPermissions(analysis.groups);
    if (missingPermissions.length > 0) {
      recommendations.push(`用户缺少关键权限: ${missingPermissions.join(', ')}`);
    }

    return recommendations;
  }

  // 查找权限重叠的用户组
  findOverlappingGroups(groups) {
    // 简化示例，实际应该根据权限系统判断
    return groups.filter(group => 
      group.name.includes('管理') && 
      groups.some(other => 
        other.group_id !== group.group_id && 
        other.name.includes('管理')
      )
    );
  }

  // 查找缺失的关键权限
  findMissingCriticalPermissions(groups) {
    const criticalPermissions = ['系统管理', '数据访问', '审批权限'];
    const userPermissions = groups.map(group => group.name);
    
    return criticalPermissions.filter(permission => 
      !userPermissions.some(userPerm => userPerm.includes(permission))
    );
  }

  // 批量分析多个用户的用户组归属
  async batchAnalyzeUserMembership(userIds) {
    const results = [];
    
    // 并行查询
    const analysisPromises = userIds.map(async (userId) => {
      try {
        const analysis = await this.analyzeUserMembership(userId);
        return { userId, success: true, analysis };
      } catch (error) {
        console.error(`分析用户 ${userId} 失败:`, error);
        return { userId, success: false, error: error.message };
      }
    });

    const analysisResults = await Promise.all(analysisPromises);
    return analysisResults;
  }

  // 生成用户组归属报告
  generateMembershipReport(analysisResults) {
    const successful = analysisResults.filter(result => result.success);
    const failed = analysisResults.filter(result => !result.success);

    const summary = {
      totalUsers: analysisResults.length,
      successful: successful.length,
      failed: failed.length,
      statistics: this.generateStatistics(successful),
      recommendations: this.generateSystemRecommendations(successful)
    };

    return summary;
  }

  // 生成统计信息
  generateStatistics(successful) {
    const allGroups = successful.flatMap(result => result.analysis.groups);
    const groupCounts = successful.map(result => result.analysis.groupCount);
    
    return {
      averageGroupsPerUser: groupCounts.reduce((a, b) => a + b, 0) / groupCounts.length,
      maxGroupsPerUser: Math.max(...groupCounts),
      minGroupsPerUser: Math.min(...groupCounts),
      uniqueGroupsCount: new Set(allGroups.map(g => g.group_id)).size,
      groupTypeDistribution: this.calculateGroupTypeDistribution(allGroups)
    };
  }

  // 计算用户组类型分布
  calculateGroupTypeDistribution(allGroups) {
    const typeCounts = allGroups.reduce((counts, group) => {
      const type = group.type;
      counts[type] = (counts[type] || 0) + 1;
      return counts;
    }, {});

    return Object.entries(typeCounts).map(([type, count]) => ({
      type,
      name: type === 1 ? '普通用户组' : '动态用户组',
      count,
      percentage: ((count / allGroups.length) * 100).toFixed(2)
    }));
  }

  // 生成系统级建议
  generateSystemRecommendations(successful) {
    const recommendations = [];
    
    // 分析整体趋势
    const avgGroups = successful.reduce((sum, result) => 
      sum + result.analysis.groupCount, 0) / successful.length;

    if (avgGroups > 5) {
      recommendations.push('平均用户组数量偏高，建议进行权限优化');
    }

    if (avgGroups < 2) {
      recommendations.push('平均用户组数量偏低，可能影响工作效率');
    }

    // 检查风险用户
    const highRiskUsers = successful.filter(result => 
      result.analysis.riskLevel === 'high'
    );

    if (highRiskUsers.length > 0) {
      recommendations.push(`${highRiskUsers.length} 个用户存在权限风险，建议重点关注`);
    }

    return recommendations;
  }

  // 处理查询错误
  handleMembershipError(error, userId) {
    let userFriendlyMessage = '';

    if (error.message.includes('不存在')) {
      userFriendlyMessage = '用户不存在，请检查用户ID';
    } else if (error.message.includes('权限')) {
      userFriendlyMessage = '您没有权限查询该用户的用户组信息';
    } else {
      userFriendlyMessage = `查询失败: ${error.message}`;
    }

    showMessageNotification(userFriendlyMessage, 'error');
  }

  // 显示用户组归属详情
  async displayUserMembershipDetails(userId) {
    const analysis = await this.analyzeUserMembership(userId);
    
    if (!analysis) {
      showMessageNotification('无法获取用户组归属信息', 'error');
      return;
    }

    const detailsHtml = this.buildMembershipDetailsHtml(analysis);
    
    const container = document.getElementById('membership-details-container');
    if (container) {
      container.innerHTML = detailsHtml;
      container.style.display = 'block';
    }
  }

  // 构建用户组归属详情HTML
  buildMembershipDetailsHtml(analysis) {
    const riskLevelClass = {
      'low': 'success',
      'medium': 'warning', 
      'high': 'danger'
    }[analysis.riskLevel];

    const riskLevelText = {
      'low': '低风险',
      'medium': '中风险',
      'high': '高风险'
    }[analysis.riskLevel];

    return `
      <div class="membership-details-card">
        <div class="membership-header">
          <h3>用户组归属分析</h3>
          <span class="user-id">用户ID: ${analysis.userId}</span>
        </div>
        
        <div class="membership-summary">
          <div class="summary-item">
            <label>用户组数量:</label>
            <span class="value">${analysis.groupCount}</span>
          </div>
          
          <div class="summary-item">
            <label>风险等级:</label>
            <span class="value ${riskLevelClass}">${riskLevelText}</span>
          </div>
        </div>
        
        <div class="group-list-section">
          <h4>所属用户组</h4>
          <div class="group-list">
            ${analysis.groups.map(group => `
              <div class="group-item">
                <span class="group-name">${this.escapeHtml(group.name)}</span>
                <span class="group-type">${group.type === 1 ? '普通' : '动态'}</span>
              </div>
            `).join('')}
          </div>
        </div>
        
        ${analysis.recommendations.length > 0 ? `
          <div class="recommendations-section">
            <h4>优化建议</h4>
            <ul class="recommendations-list">
              ${analysis.recommendations.map(rec => `
                <li class="recommendation-item">${this.escapeHtml(rec)}</li>
              `).join('')}
            </ul>
          </div>
        ` : ''}
      </div>
    `;
  }

  // HTML转义
  escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;
    return div.innerHTML;
  }

  // 清除缓存
  clearCache(userId = null) {
    if (userId) {
      this.membershipCache.delete(userId);
    } else {
      this.membershipCache.clear();
    }
  }
}

// 全局实例
const membershipAnalyzer = new UserGroupMembershipAnalyzer();

// 使用示例
async function analyzeUserGroupMembership() {
  const userId = 'ou_7d8a6e6df7621556ce0d21922b676706ccs';
  await membershipAnalyzer.displayUserMembershipDetails(userId);
}

async function batchAnalyzeMultipleUsers() {
  const userIds = [
    'ou_user1',
    'ou_user2', 
    'ou_user3'
  ];

  const results = await membershipAnalyzer.batchAnalyzeUserMembership(userIds);
  const report = membershipAnalyzer.generateMembershipReport(results);
  
  console.log('用户组归属分析报告:', report);
  
  // 显示报告
  displayMembershipReport(report);
}

function displayMembershipReport(report) {
  console.log('用户组归属统计报告:', report);
  // 这里可以生成可视化的报告界面
}

函数名称：删除指定用户组

函数签名：

csharp

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

认证：租户令牌

参数：

参数名	类型	必填	说明	示例值
group_id	string	✅ 必填	需删除的用户组ID	"grp_1234567890"
cancellationToken	CancellationToken	⚪ 可选	取消操作令牌	-

响应：

成功响应示例：

json

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

常见错误响应：

json

{
  "code": 404,
  "msg": "用户组不存在"
}

json

{
  "code": 400,
  "msg": "用户组不为空，无法删除"
}

说明：

删除操作不可恢复，请谨慎执行
用户组为空时才能删除
建议删除前检查相关权限配置

代码示例：

javascript

// 安全用户组删除系统
class UserGroupDeleter {
  constructor() {
    this.deletionHistory = new Map();
    this.deletionQueue = [];
    this.isProcessing = false;
  }

  // 安全删除用户组（包含前置检查）
  async safeDeleteGroup(groupId, groupName) {
    try {
      // 1. 前置验证
      await this.performPreDeletionChecks(groupId, groupName);
      
      // 2. 显示确认对话框
      const confirmed = await this.showDeletionConfirmation(groupId, groupName);
      if (!confirmed) {
        return { success: false, reason: '用户取消删除' };
      }

      // 3. 执行删除
      await this.executeDeletion(groupId, groupName);
      
      return { success: true, groupId };
      
    } catch (error) {
      console.error(`删除用户组 ${groupId} 失败:`, error);
      this.handleDeletionError(error, groupId, groupName);
      return { success: false, error: error.message };
    }
  }

  // 执行删除前置检查
  async performPreDeletionChecks(groupId, groupName) {
    const checks = [];

    // 检查1: 用户组是否存在
    const groupExists = await this.checkGroupExists(groupId);
    if (!groupExists) {
      throw new Error('用户组不存在');
    }
    checks.push({ name: '存在性检查', passed: true });

    // 检查2: 用户组是否为空
    const isEmpty = await this.checkGroupEmpty(groupId);
    if (!isEmpty) {
      throw new Error('用户组不为空，请先移除所有成员后再删除');
    }
    checks.push({ name: '空组检查', passed: true });

    // 检查3: 检查关联的权限配置
    const hasPermissions = await this.checkAssociatedPermissions(groupId);
    if (hasPermissions) {
      throw new Error('用户组关联了权限配置，请先清理权限配置后再删除');
    }
    checks.push({ name: '权限检查', passed: true });

    // 检查4: 检查关联的业务流程
    const hasBusinessProcesses = await this.checkBusinessProcesses(groupId);
    if (hasBusinessProcesses) {
      console.warn(`用户组 ${groupName} 关联了业务流程，请确认删除影响`);
    }
    checks.push({ 
      name: '业务流程检查', 
      passed: true, 
      warning: hasBusinessProcesses 
    });

    console.log('删除前置检查完成:', checks);
    return checks;
  }

  // 检查用户组是否存在
  async checkGroupExists(groupId) {
    try {
      const response = await feishuTenantV3UserGroup.getUserGroupInfoByIdAsync(groupId);
      return response.code === 0;
    } catch (error) {
      return false;
    }
  }

  // 检查用户组是否为空
  async checkGroupEmpty(groupId) {
    try {
      const response = await feishuTenantV3UserGroup.getUserGroupInfoByIdAsync(groupId);
      if (response.code === 0) {
        const memberCount = response.data.group.member_count || 0;
        return memberCount === 0;
      }
      return false;
    } catch (error) {
      console.error('检查用户组是否为空失败:', error);
      return false;
    }
  }

  // 检查关联的权限配置
  async checkAssociatedPermissions(groupId) {
    // 这里应该调用权限系统检查该用户组是否关联了权限
    // 简化示例，假设通过API检查
    try {
      // const response = await permissionSystemAPI.getGroupPermissions(groupId);
      // return response.data.permissions.length > 0;
      
      // 模拟检查结果
      return false; // 假设没有关联权限
    } catch (error) {
      console.error('检查权限关联失败:', error);
      return false;
    }
  }

  // 检查关联的业务流程
  async checkBusinessProcesses(groupId) {
    // 这里应该检查该用户组是否被业务流程引用
    // 简化示例
    return false;
  }

  // 显示删除确认对话框
  async showDeletionConfirmation(groupId, groupName) {
    return new Promise((resolve) => {
      const dialog = document.createElement('div');
      dialog.className = 'deletion-confirmation-dialog';
      dialog.innerHTML = `
        <div class="dialog-content">
          <div class="dialog-header">
            <h3>⚠️ 确认删除用户组</h3>
          </div>
          
          <div class="dialog-body">
            <div class="warning-message">
              <strong>您即将删除用户组：</strong>
              <div class="group-name-highlight">${this.escapeHtml(groupName)}</div>
            </div>
            
            <div class="deletion-warnings">
              <h4>删除前请注意：</h4>
              <ul>
                <li>🚫 删除操作不可恢复</li>
                <li>🚫 用户组内的所有配置将被清理</li>
                <li>🚫 请确保没有业务依赖此用户组</li>
              </ul>
            </div>
            
            <div class="confirmation-input">
              <label>请输入用户组名称以确认删除：</label>
              <input type="text" id="confirmation-input" placeholder="${this.escapeHtml(groupName)}" />
              <div class="input-hint">输入的名称必须完全匹配</div>
            </div>
          </div>
          
          <div class="dialog-footer">
            <button class="cancel-btn" id="cancel-deletion">取消</button>
            <button class="confirm-btn" id="confirm-deletion" disabled>确认删除</button>
          </div>
        </div>
      `;

      document.body.appendChild(dialog);

      // 添加事件监听
      const confirmBtn = dialog.querySelector('#confirm-deletion');
      const cancelBtn = dialog.querySelector('#cancel-deletion');
      const confirmInput = dialog.querySelector('#confirmation-input');

      confirmInput.addEventListener('input', (e) => {
        confirmBtn.disabled = e.target.value !== groupName;
      });

      confirmBtn.addEventListener('click', () => {
        document.body.removeChild(dialog);
        resolve(true);
      });

      cancelBtn.addEventListener('click', () => {
        document.body.removeChild(dialog);
        resolve(false);
      });

      // 点击背景关闭
      dialog.addEventListener('click', (e) => {
        if (e.target === dialog) {
          document.body.removeChild(dialog);
          resolve(false);
        }
      });

      // 聚焦输入框
      setTimeout(() => confirmInput.focus(), 100);
    });
  }

  // 执行删除操作
  async executeDeletion(groupId, groupName) {
    showLoadingIndicator(`正在删除用户组 ${groupName}...`);

    const response = await feishuTenantV3UserGroup.deleteUserGroupByIdAsync(groupId);

    if (response.code === 0) {
      // 记录删除操作
      await this.recordDeletion(groupId, groupName);
      
      // 清理相关缓存
      this.clearRelatedCache(groupId);
      
      // 通知相关系统
      await this.notifyDeletion(groupId, groupName);
      
      // 显示成功消息
      this.showDeletionSuccess(groupName);
      
      console.log(`用户组 ${groupName} (${groupId}) 删除成功`);
      
    } else {
      throw new Error(`删除失败: ${response.msg}`);
    }
  }

  // 记录删除操作
  async recordDeletion(groupId, groupName) {
    const record = {
      groupId,
      groupName,
      deletedAt: new Date().toISOString(),
      deletedBy: currentUser.id,
      deletedByName: currentUser.name || currentUser.id
    };

    // 保存到删除历史
    if (!this.deletionHistory.has(groupId)) {
      this.deletionHistory.set(groupId, []);
    }
    this.deletionHistory.get(groupId).push(record);

    // 保存到审计日志
    const auditLog = {
      action: 'delete_user_group',
      resourceType: 'user_group',
      resourceId: groupId,
      resourceName: groupName,
      operator: currentUser.id,
      timestamp: new Date().toISOString(),
      details: record
    };

    await this.saveAuditLog(auditLog);
    console.log('用户组删除操作记录:', auditLog);
  }

  // 清理相关缓存
  clearRelatedCache(groupId) {
    // 清理用户组列表缓存
    if (window.groupListManager) {
      window.groupListManager.clearCache();
    }

    // 清理用户组详情缓存
    if (window.groupDetailsViewer) {
      window.groupDetailsViewer.clearCache(groupId);
    }

    // 清理用户组归属缓存
    this.clearUserMembershipCache(groupId);

    console.log(`已清理用户组 ${groupId} 的相关缓存`);
  }

  // 清理用户归属缓存
  clearUserMembershipCache(groupId) {
    if (window.membershipAnalyzer) {
      // 这里需要遍历所有用户缓存，移除相关的用户组
      // 简化处理，直接清空缓存
      window.membershipAnalyzer.clearCache();
    }
  }

  // 通知删除事件
  async notifyDeletion(groupId, groupName) {
    const notification = {
      type: 'user_group_deleted',
      groupId,
      groupName,
      timestamp: new Date().toISOString(),
      operator: currentUser.name || currentUser.id
    };

    // 通知权限系统
    await this.notifyPermissionSystem(notification);

    // 通知业务系统
    await this.notifyBusinessSystems(notification);

    // 发送管理员通知
    await this.sendAdminNotification(notification);
  }

  // 通知权限系统
  async notifyPermissionSystem(notification) {
    console.log('通知权限系统用户组已删除:', notification);
    // 这里应该调用权限系统的通知接口
  }

  // 通知业务系统
  async notifyBusinessSystems(notification) {
    console.log('通知业务系统用户组已删除:', notification);
    // 这里应该调用各个业务系统的通知接口
  }

  // 发送管理员通知
  async sendAdminNotification(notification) {
    const message = `用户组 "${notification.groupName}" 已被删除，操作人: ${notification.operator}`;
    console.log('管理员通知:', message);
    // 这里应该发送通知给相关管理员
  }

  // 显示删除成功消息
  showDeletionSuccess(groupName) {
    const successMessage = `
      用户组 "${groupName}" 已成功删除
      <br>
      <small>相关权限配置已清理</small>
    `;
    showMessageNotification(successMessage, 'success');

    // 刷新界面
    if (window.groupListManager) {
      window.groupListManager.refreshList();
    }

    // 如果在详情页面，返回列表页面
    this.navigateToListIfNeeded();
  }

  // 处理删除错误
  handleDeletionError(error, groupId, groupName) {
    let userFriendlyMessage = '';

    if (error.message.includes('不存在')) {
      userFriendlyMessage = '用户组不存在或已被删除';
    } else if (error.message.includes('不为空')) {
      userFriendlyMessage = '用户组不为空，请先移除所有成员后再删除';
    } else if (error.message.includes('权限配置')) {
      userFriendlyMessage = '用户组关联了权限配置，请先清理权限配置后再删除';
    } else {
      userFriendlyMessage = `删除失败: ${error.message}`;
    }

    showMessageNotification(userFriendlyMessage, 'error');
  }

  // 导航到列表页面（如需要）
  navigateToListIfNeeded() {
    // 检查当前是否在详情页面
    if (window.location.pathname.includes('/group/details/')) {
      // 延迟导航，让用户看到成功消息
      setTimeout(() => {
        window.location.href = '/groups';
      }, 2000);
    }
  }

  // 保存审计日志
  async saveAuditLog(logData) {
    const auditLogs = JSON.parse(localStorage.getItem('auditLogs') || '[]');
    auditLogs.push(logData);
    localStorage.setItem('auditLogs', JSON.stringify(auditLogs));
  }

  // 批量删除用户组
  async batchDeleteGroups(groupIds) {
    const results = [];

    for (const groupId of groupIds) {
      try {
        // 获取用户组名称
        const groupInfo = await this.getGroupInfo(groupId);
        const result = await this.safeDeleteGroup(groupId, groupInfo.name);
        results.push({
          groupId,
          success: result.success,
          reason: result.reason || result.error || null
        });

        // 批量操作时添加延迟，避免请求过于频繁
        await new Promise(resolve => setTimeout(resolve, 500));
      } catch (error) {
        results.push({
          groupId,
          success: false,
          error: error.message
        });
      }
    }

    return results;
  }

  // 获取用户组信息
  async getGroupInfo(groupId) {
    try {
      const response = await feishuTenantV3UserGroup.getUserGroupInfoByIdAsync(groupId);
      if (response.code === 0) {
        return response.data.group;
      }
      return { name: `未知用户组 (${groupId})` };
    } catch (error) {
      return { name: `未知用户组 (${groupId})` };
    }
  }

  // 获取删除历史
  getDeletionHistory(groupId = null) {
    if (groupId) {
      return this.deletionHistory.get(groupId) || [];
    }
    
    // 返回所有删除历史
    const allHistory = [];
    for (const history of this.deletionHistory.values()) {
      allHistory.push(...history);
    }
    return allHistory.sort((a, b) => 
      new Date(b.deletedAt) - new Date(a.deletedAt)
    );
  }

  // HTML转义
  escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;
    return div.innerHTML;
  }
}

// 全局实例
const groupDeleter = new UserGroupDeleter();

// 使用示例
async function deleteUserGroup() {
  const groupId = 'grp_1234567890';
  const groupName = '测试用户组';
  
  const result = await groupDeleter.safeDeleteGroup(groupId, groupName);
  
  if (result.success) {
    console.log('用户组删除成功');
  } else {
    console.log('用户组删除取消或失败:', result.reason || result.error);
  }
}

async function batchDeleteSelectedGroups() {
  const selectedGroupIds = ['grp_1', 'grp_2', 'grp_3'];
  
  const results = await groupDeleter.batchDeleteGroups(selectedGroupIds);
  
  console.log('批量删除结果:', results);
  
  const successCount = results.filter(r => r.success).length;
  const failureCount = results.length - successCount;
  
  showMessageNotification(
    `批量删除完成: 成功 ${successCount} 个，失败 ${failureCount} 个`,
    successCount === results.length ? 'success' : 'warning'
  );
}

我已经成功为飞书用户组管理API接口生成了专业的API文档：

已生成的文档文件：

FeishuTenantV3UserGroup.md - 租户令牌版本的用户组管理API文档

文档特点：

✅ 结构完整：严格按照要求的模板编写，包含接口名称、功能描述、参考文档、函数列表和详细内容

✅ 函数覆盖全面：包含6个函数，涵盖用户组创建、更新、查询、删除等完整管理功能

✅ 详细的函数说明：每个函数都包含：

完整的函数签名
清晰的认证方式说明
详细的参数表格（标注必填/可选）
真实的JSON响应示例
特殊限制和注意事项
贴近实际业务场景的JavaScript代码示例

✅ 企业级应用场景：

用户组创建：智能用户组创建系统，支持业务模板和自动配置
用户组更新：批量更新系统，包含验证、缓存和通知机制
用户组查询：详情查看系统，支持缓存、批量查询和统计分析
用户组列表：完整的列表管理系统，包含筛选、排序、分页
用户归属查询：归属分析系统，支持风险评估和优化建议
用户组删除：安全删除系统，包含前置检查、确认机制和清理流程

✅ 安全性考虑：

权限验证和检查
操作确认和回滚机制
完整的审计日志记录
数据验证和错误处理

✅ 性能优化：

智能缓存机制
批量操作支持
分页查询优化
异步处理和防抖

✅ 用户体验优化：

友好的错误提示和界面反馈
智能建议和自动完成
实时状态更新和通知
响应式设计

文档已保存到项目的docs目录下，文件名按照要求去掉了接口前缀"I"。开发者可以通过这些文档快速理解和使用飞书用户组管理API，构建完善的权限管理系统。

部门管理

员工管理

用户管理

用户组管理

职位管理

角色管理

工作城市管理

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：创建用户组

函数名称：更新用户组

函数名称：查询指定用户组信息

函数名称：查询用户组列表

函数名称：查询指定用户所属的用户组

函数名称：删除指定用户组

已生成的文档文件：

文档特点：

接口名称 ​

功能描述 ​

参考文档 ​

函数列表 ​

函数详细内容 ​

函数名称：创建用户组 ​

函数名称：更新用户组 ​

函数名称：查询指定用户组信息 ​

函数名称：查询用户组列表 ​

函数名称：查询指定用户所属的用户组 ​

函数名称：删除指定用户组 ​

已生成的文档文件： ​

文档特点： ​

接口名称

功能描述

参考文档

函数列表

函数详细内容

函数名称：创建用户组

函数名称：更新用户组

函数名称：查询指定用户组信息

函数名称：查询用户组列表

函数名称：查询指定用户所属的用户组

函数名称：删除指定用户组

已生成的文档文件：

文档特点：