mjava-guangming/mjava/src/main/java/com/malk/service/dingtalk/DDClient_Role.java

package com.malk.service.dingtalk;

import java.util.Collection;
import java.util.List;
import java.util.Map;

/**
 * 钉钉应用 + 角色管理
 * <p>
 * Phase 1:getMicroAppVisibleScopes + roleGroupCreate(数据落库 + 全局角色组)
 * Phase 2:roleCreate + roleAddUsers + roleDeleteUsers(每应用一角色 + 全量绑人员)
 *
 * @apiNote https://open.dingtalk.com/document/orgapp/contacts-overview
 */
public interface DDClient_Role {

    /**
     * 获取微应用可见范围
     *
     * @return Map { deptVisibleScopes: List<Long>, userVisibleScopes: List<String>, isHidden: Boolean }
     * @apiNote https://open.dingtalk.com/document/orgapp/queries-the-visible-range-of-a-microapp
     */
    Map getMicroAppVisibleScopes(String access_token, long agentId);

    /**
     * 创建角色组
     *
     * @return groupId(字符串形式)
     * @apiNote https://open.dingtalk.com/document/development/add-a-role-group
     */
    String roleGroupCreate(String access_token, String name);

    /**
     * 创建角色
     *
     * @return roleId(字符串形式)
     * @apiNote https://open.dingtalk.com/document/development/add-roles
     */
    String roleCreate(String access_token, String roleName, String groupId);

    /**
     * 批量增加员工角色(单批最多 100 用户;impl 内部自动分批)
     *
     * @apiNote https://open.dingtalk.com/document/development/add-role-information-to-employees-in-batches
     */
    void roleAddUsers(String access_token, String roleId, Collection<String> userIds);

    /**
     * 批量删除员工角色(单批最多 100 用户;impl 内部自动分批)
     *
     * @apiNote https://open.dingtalk.com/document/development/delete-the-color-information-of-employee-corners-in-batches
     */
    void roleDeleteUsers(String access_token, String roleId, Collection<String> userIds);

    /**
     * 更新角色名
     *
     * @apiNote https://open.dingtalk.com/document/development/update-role-information
     */
    void roleUpdate(String access_token, String roleId, String roleName);

    /**
     * 设置应用可见范围(支持 dept/user/role 三种维度 add/del)
     * <p>
     * 钉钉单次 delUserIds 上限约 50,业务方需自行分批
     *
     * @apiNote https://open.dingtalk.com/document/development/update-the-visible-range-of-micro-applications
     */
    void setMicroAppVisibleScopes(String access_token, long agentId,
                                  List<Long> addDeptIds, List<String> addUserIds, List<String> addRoleIds,
                                  List<Long> delDeptIds, List<String> delUserIds, List<String> delRoleIds);

    /**
     * 获取企业自建应用列表(返回 [ {agentId, appKey, name}, ... ])
     *
     * @apiNote https://open.dingtalk.com/document/development/obtain-the-list-of-internal-h5-applications-created-by-the
     */
    List<Map> listMicroApp(String access_token);
}