minglei/src/main/java/com/malk/minglei/service/employee/DingTalkEmployeeRosterClient.java

package com.malk.minglei.service.employee;

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

/**
 * 钉钉智能人事花名册接口客户端。
 */
public interface DingTalkEmployeeRosterClient {

    /**
     * 从用户父部门路径解析根部门下的一级部门 ID。
     *
     * @param accessToken 钉钉访问令牌
     * @param userId 员工钉钉用户 ID
     * @param departmentId 员工部门列表首个部门 ID，多部门时优先使用其所在路径
     * @return 一级部门 ID；无父部门或仅属于根部门时返回 null
     */
    Long getFirstDepartmentId(String accessToken, String userId, Long departmentId);

    /**
     * 查询部门名称，接口失败或名称缺失时抛出异常。
     *
     * @param accessToken 钉钉访问令牌
     * @param departmentId 钉钉部门 ID
     * @return 部门名称
     */
    String getDepartmentName(String accessToken, Long departmentId);

    /**
     * 查询用户详情中的直属主管钉钉 ID。
     *
     * @param accessToken 钉钉访问令牌
     * @param userId 员工钉钉用户 ID
     * @return 直属主管钉钉用户 ID；未配置主管时返回 null
     * @throws IllegalStateException 钉钉接口失败或返回无效的用户详情
     */
    String getManagerUserId(String accessToken, String userId);

    /**
     * 查询可用的花名册字段分组。
     *
     * @param accessToken 钉钉访问令牌
     * @param agentId 应用 AgentId
     * @return 花名册字段分组列表
     */
    List<Map> listRosterFieldGroups(String accessToken, Number agentId);

    /**
     * 批量查询指定用户的花名册字段值。
     *
     * @param accessToken 钉钉访问令牌
     * @param userIds 钉钉用户 ID 列表
     * @param agentId 应用 AgentId
     * @param fieldCodes 需要查询的字段编码
     * @return 用户花名册记录列表
     */
    List<Map> listEmployeeRoster(String accessToken, List<String> userIds, Number agentId, List<String> fieldCodes);
}