/**
 * 定义包名，明确该接口所属的模块和服务层目录，用于组织系统用户角色相关的服务类。
 */
package com.yf.exam.modules.sys.user.service;

/**
 * 导入 MyBatis-Plus 框架的分页元数据接口，用于表示分页查询结果，包含总记录数、当前页码等信息。
 */
import com.baomidou.mybatisplus.core.metadata.IPage;
/**
 * 导入 MyBatis-Plus 框架的扩展服务接口，提供通用的 CRUD 操作方法，减少重复代码编写。
 */
import com.baomidou.mybatisplus.extension.service.IService;
/**
 * 导入系统用户角色数据传输对象类，用于在不同层之间传输用户角色相关的数据，避免直接暴露实体类。
 */
import com.yf.exam.modules.sys.user.dto.SysUserRoleDTO;
/**
 * 导入系统用户角色实体类，用于映射数据库中的用户角色表，封装用户角色的属性信息。
 */
import com.yf.exam.modules.sys.user.entity.SysUserRole;
/**
 * 导入自定义的分页请求数据传输对象类，用于封装分页查询的请求参数，如当前页码、每页记录数等。
 */
import com.yf.exam.core.api.dto.PagingReqDTO;

import java.util.List;

/**
 * <p>
 * 用户角色业务类接口，定义了与系统用户角色相关的业务方法。
 * 继承自 MyBatis-Plus 的 IService 接口，可使用其提供的通用服务方法。
 * </p>
 *
 * @author 聪明笨狗
 * @since 2020-04-13 16:57
 */
public interface SysUserRoleService extends IService<SysUserRole> {

    /**
     * 分页查询用户角色数据。
     * 根据传入的分页请求参数，从数据库中查询用户角色数据并进行分页处理。
     *
     * @param reqDTO 分页请求数据传输对象，包含分页查询的条件和参数。
     * @return 分页查询结果，包含符合条件的用户角色数据传输对象列表。
     */
    IPage<SysUserRoleDTO> paging(PagingReqDTO<SysUserRoleDTO> reqDTO);

    /**
     * 查找指定用户的角色列表。
     * 根据用户 ID 从数据库中查询该用户关联的所有角色 ID。
     *
     * @param userId 用户的唯一标识。
     * @return 该用户关联的角色 ID 列表。
     */
    List<String> listRoles(String userId);

    /**
     * 保存指定用户的全部角色。
     * 先删除该用户原有的所有角色关联，再添加新的角色关联。
     *
     * @param userId 用户的唯一标识。
     * @param ids 要保存的角色 ID 列表。
     * @return 保存操作完成后，返回保存的角色 ID 相关信息（具体格式由实现类定义）。
     */
    String saveRoles(String userId, List<String> ids);

    /**
     * 判断指定用户是否为学生角色。
     * 根据用户 ID 检查该用户是否关联了学生角色。
     *
     * @param userId 用户的唯一标识。
     * @return 如果用户是学生角色返回 true，否则返回 false。
     */
    boolean isStudent(String userId);

    /**
     * 判断指定用户是否为老师角色。
     * 根据用户 ID 检查该用户是否关联了老师角色。
     *
     * @param userId 用户的唯一标识。
     * @return 如果用户是老师角色返回 true，否则返回 false。
     */
    boolean isTeacher(String userId);

    /**
     * 判断指定用户是否为管理员角色。
     * 根据用户 ID 检查该用户是否关联了管理员角色。
     *
     * @param userId 用户的唯一标识。
     * @return 如果用户是管理员角色返回 true，否则返回 false。
     */
    boolean isAdmin(String userId);
}