mjava-ai/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);

    /**
     * 删除角色。
     *
     * @param access_token 钉钉 accessToken
     * @param roleId       角色 ID
     * @apiNote https://open.dingtalk.com/document/orgapp/delete-role
     */
    void roleDelete(String access_token, String roleId);

    /**
     * 查询角色列表。
     *
     * @param access_token 钉钉 accessToken
     * @param body_ext     可选参数：size、offset
     * @return 钉钉角色列表 result
     * @apiNote https://open.dingtalk.com/document/orgapp/obtains-a-list-of-enterprise-roles
     */
    Map roleList(String access_token, Map body_ext);

    /**
     * 查询角色详情。
     *
     * @param access_token 钉钉 accessToken
     * @param roleId       角色 ID
     * @return 钉钉角色详情 result
     * @apiNote https://open.dingtalk.com/document/orgapp/queries-role-details
     */
    Map roleGet(String access_token, String roleId);

    /**
     * 查询角色下员工列表。
     *
     * @param access_token 钉钉 accessToken
     * @param roleId       角色 ID
     * @param size         每页数量
     * @param offset       分页偏移
     * @return 钉钉角色员工列表 result
     * @apiNote https://open.dingtalk.com/document/orgapp/obtain-the-list-of-employees-of-a-role
     */
    Map roleListEmployees(String access_token, String roleId, long size, long offset);

    /**
     * 设置应用可见范围(支持 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);
}