// 声明当前类所在的包，表明该类属于系统用户控制器模块
package com.yf.exam.modules.sys.user.controller;

// 导入 MyBatis-Plus 的查询条件构造器，用于构建数据库查询条件
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
// 导入 MyBatis-Plus 的分页元数据接口，用于处理分页查询结果
import com.baomidou.mybatisplus.core.metadata.IPage;
// 导入自定义的 API 统一响应类，用于封装接口返回数据
import com.yf.exam.core.api.ApiRest;
// 导入自定义的基础控制器类，提供一些通用的控制器方法
import com.yf.exam.core.api.controller.BaseController;
// 导入自定义的分页请求数据传输对象类，用于封装分页查询请求参数
import com.yf.exam.core.api.dto.PagingReqDTO;
// 导入自定义的 Bean 映射工具类，用于对象属性的复制
import com.yf.exam.core.utils.BeanMapper;
// 导入系统角色数据传输对象类，用于在不同层之间传输角色信息
import com.yf.exam.modules.sys.user.dto.SysRoleDTO;
// 导入系统角色实体类，对应数据库中的角色表
import com.yf.exam.modules.sys.user.entity.SysRole;
// 导入系统角色服务接口，用于调用角色相关的业务逻辑
import com.yf.exam.modules.sys.user.service.SysRoleService;
// 导入 Swagger 注解，用于生成 API 文档，标记控制器的标签
import io.swagger.annotations.Api;
// 导入 Swagger 注解，用于生成 API 文档，标记接口的操作描述
import io.swagger.annotations.ApiOperation;
// 导入 Shiro 注解，用于权限控制，要求用户具有指定角色才能访问接口
import org.apache.shiro.authz.annotation.RequiresRoles;
// 导入 Spring 框架的依赖注入注解，用于自动注入依赖的 Bean
import org.springframework.beans.factory.annotation.Autowired;
// 导入 Spring 框架的请求体注解，用于将请求体中的数据绑定到方法参数上
import org.springframework.web.bind.annotation.RequestBody;
// 导入 Spring 框架的请求映射注解，用于映射请求路径
import org.springframework.web.bind.annotation.RequestMapping;
// 导入 Spring 框架的请求方法注解，用于指定请求的 HTTP 方法
import org.springframework.web.bind.annotation.RequestMethod;
// 导入 Spring 框架的控制器注解，标记该类为 RESTful 风格的控制器
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

/**
 * <p>
 * 管理用户控制器，处理与系统角色相关的接口请求
 * </p>
 *
 * @author 聪明笨狗
 * @since 2020-04-13 16:57
 */
// 为 Swagger 文档标记该控制器的标签为 "管理用户"
@Api(tags = {"管理用户"})
// 标记该类为 RESTful 风格的控制器，返回数据直接作为 HTTP 响应体
@RestController
// 定义该控制器处理的请求路径前缀
@RequestMapping("/exam/api/sys/role")
public class SysRoleController extends BaseController {

    // 自动注入系统角色服务实例，用于调用角色相关的业务逻辑
    @Autowired
    private SysRoleService baseService;

    /**
     * 分页查找系统角色信息
     *
     * @param reqDTO 分页请求数据传输对象，包含分页查询的条件和参数
     * @return 封装了分页查询结果的 API 统一响应对象
     */
    // 要求用户具有 "sa" 角色才能访问该接口
    @RequiresRoles("sa")
    // 为 Swagger 文档标记该接口的操作描述为 "分页查找"
    @ApiOperation(value = "分页查找")
    // 映射请求路径为 "/paging"，并指定请求方法为 POST
    @RequestMapping(value = "/paging", method = { RequestMethod.POST})
    public ApiRest<IPage<SysRoleDTO>> paging(@RequestBody PagingReqDTO<SysRoleDTO> reqDTO) {

        // 调用角色服务的分页查询方法，进行分页查询并将结果转换为角色数据传输对象
        IPage<SysRoleDTO> page = baseService.paging(reqDTO);
        // 调用父类的成功响应方法，返回包含分页结果的响应对象
        return super.success(page);
    }

    /**
     * 查找系统角色列表，每次最多返回 200 条数据
     *
     * @return 封装了角色列表信息的 API 统一响应对象
     */
    // 要求用户具有 "sa" 角色才能访问该接口
    @RequiresRoles("sa")
    // 为 Swagger 文档标记该接口的操作描述为 "查找列表"
    @ApiOperation(value = "查找列表")
    // 映射请求路径为 "/list"，并指定请求方法为 POST
    @RequestMapping(value = "/list", method = { RequestMethod.POST})
    public ApiRest<List<SysRoleDTO>> list() {

        // 创建一个 MyBatis-Plus 的查询条件构造器，用于构建查询条件
        QueryWrapper<SysRole> wrapper = new QueryWrapper<>();

        // 调用角色服务的列表查询方法，根据查询条件获取角色实体列表
        List<SysRole> list = baseService.list(wrapper);

        // 使用 Bean 映射工具类将角色实体列表转换为角色数据传输对象列表
        List<SysRoleDTO> dtoList = BeanMapper.mapList(list, SysRoleDTO.class);

        // 调用父类的成功响应方法，返回包含角色列表的响应对象
        return super.success(dtoList);
    }
}