// 声明当前接口所在的包，明确该接口属于系统用户服务模块
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.SysUserDTO;
// 导入系统用户保存请求数据传输对象类，用于封装用户保存操作的请求参数
import com.yf.exam.modules.sys.user.dto.request.SysUserSaveReqDTO;
// 导入系统用户登录响应数据传输对象类，用于封装用户登录操作的响应信息
import com.yf.exam.modules.sys.user.dto.response.SysUserLoginDTO;
// 导入系统用户实体类，用于映射数据库中的用户表
import com.yf.exam.modules.sys.user.entity.SysUser;
// 导入自定义的分页请求数据传输对象类，用于封装分页查询的请求参数
import com.yf.exam.core.api.dto.PagingReqDTO;

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

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

    /**
     * 用户登录方法。
     * 根据传入的用户名和密码，验证用户身份，若验证通过则返回登录信息。
     *
     * @param userName 用户名，用于标识用户身份
     * @param password 用户密码，用于验证用户身份
     * @return 系统用户登录响应数据传输对象，包含登录成功后的用户信息和令牌等
     */
    SysUserLoginDTO login(String userName, String password);

    /**
     * 根据令牌获取管理会话信息。
     * 验证传入的令牌是否有效，若有效则返回对应的用户登录信息。
     *
     * @param token 用户登录后生成的令牌，用于验证用户身份和保持会话
     * @return 系统用户登录响应数据传输对象，包含令牌对应的用户信息
     */
    SysUserLoginDTO token(String token);

    /**
     * 用户退出登录方法。
     * 使传入的令牌失效，清除用户的登录会话信息。
     *
     * @param token 用户登录后生成的令牌，用于标识用户会话
     */
    void logout(String token);

    /**
     * 修改用户资料方法。
     * 根据传入的用户数据传输对象，更新数据库中对应的用户信息。
     *
     * @param reqDTO 系统用户数据传输对象，包含要更新的用户信息
     */
    void update(SysUserDTO reqDTO);

    /**
     * 保存添加系统用户方法。
     * 根据传入的用户保存请求数据传输对象，将新用户信息保存到数据库中。
     *
     * @param reqDTO 系统用户保存请求数据传输对象，包含要添加的用户信息
     */
    void save(SysUserSaveReqDTO reqDTO);

    /**
     * 用户注册方法。
     * 根据传入的用户数据传输对象，在数据库中创建新的用户记录，并返回注册后的登录信息。
     *
     * @param reqDTO 系统用户数据传输对象，包含要注册的用户信息
     * @return 系统用户登录响应数据传输对象，包含注册成功后的用户信息和令牌等
     */
    SysUserLoginDTO reg(SysUserDTO reqDTO);

    /**
     * 快速注册方法。
     * 根据传入的用户数据传输对象，快速创建新的用户记录，并返回注册后的登录信息。
     *
     * @param reqDTO 系统用户数据传输对象，包含要快速注册的用户信息
     * @return 系统用户登录响应数据传输对象，包含快速注册成功后的用户信息和令牌等
     */
    SysUserLoginDTO quickReg(SysUserDTO reqDTO);
}