// 定义当前类所在的包，表明该类属于系统部门控制器模块
package com.yf.exam.modules.sys.depart.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;
// 导入自定义的基础单个 ID 请求数据传输对象类
import com.yf.exam.core.api.dto.BaseIdReqDTO;
// 导入自定义的基础多个 ID 请求数据传输对象类
import com.yf.exam.core.api.dto.BaseIdsReqDTO;
// 导入自定义的分页请求数据传输对象类
import com.yf.exam.core.api.dto.PagingReqDTO;
// 导入自定义的 Bean 映射工具类，用于对象属性的复制
import com.yf.exam.core.utils.BeanMapper;
// 导入系统部门数据传输对象类，用于在不同层之间传输部门信息
import com.yf.exam.modules.sys.depart.dto.SysDepartDTO;
// 导入部门排序请求数据传输对象类，用于接收部门排序的请求信息
import com.yf.exam.modules.sys.depart.dto.request.DepartSortReqDTO;
// 导入系统部门树状数据传输对象类，用于返回部门的树状结构信息
import com.yf.exam.modules.sys.depart.dto.response.SysDepartTreeDTO;
// 导入系统部门实体类，对应数据库中的部门表
import com.yf.exam.modules.sys.depart.entity.SysDepart;
// 导入系统部门服务接口，用于调用部门相关的业务逻辑
import com.yf.exam.modules.sys.depart.service.SysDepartService;
// 导入 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.BeanUtils;
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-09-02 17:25
 */
// 为 Swagger 文档标记该控制器的标签为 "部门信息"
@Api(tags={"部门信息"})
// 标记该类为 RESTful 风格的控制器，返回数据直接作为 HTTP 响应体
@RestController
// 定义该控制器处理的请求路径前缀
@RequestMapping("/exam/api/sys/depart")
public class SysDepartController extends BaseController {

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

    /**
     * 添加或修改部门信息
     * @param reqDTO 部门信息数据传输对象，包含要添加或修改的部门信息
     * @return 封装了操作结果的 API 统一响应对象
     */
    // 要求用户具有 "sa" 角色才能访问该接口
    @RequiresRoles("sa")
    // 为 Swagger 文档标记该接口的操作描述为 "添加或修改"
    @ApiOperation(value = "添加或修改")
    // 映射请求路径为 "/save"，并指定请求方法为 POST
    @RequestMapping(value = "/save", method = { RequestMethod.POST})
    public ApiRest save(@RequestBody SysDepartDTO reqDTO) {
        // 调用部门服务的保存方法，保存或更新部门信息
        baseService.save(reqDTO);
        // 调用父类的成功响应方法，返回操作成功的响应对象
        return super.success();
    }

    /**
     * 批量删除部门信息
     * @param reqDTO 包含多个部门 ID 的请求数据传输对象，用于指定要删除的部门
     * @return 封装了操作结果的 API 统一响应对象
     */
    @RequiresRoles("sa")
    @ApiOperation(value = "批量删除")
    @RequestMapping(value = "/delete", method = { RequestMethod.POST})
    public ApiRest edit(@RequestBody BaseIdsReqDTO reqDTO) {
        // 根据传入的部门 ID 列表，调用部门服务的删除方法删除部门信息
        baseService.removeByIds(reqDTO.getIds());
        return super.success();
    }

    /**
     * 查找部门详情信息
     * @param reqDTO 包含单个部门 ID 的请求数据传输对象，用于指定要查找的部门
     * @return 封装了部门详情信息的 API 统一响应对象
     */
    @RequiresRoles("sa")
    @ApiOperation(value = "查找详情")
    @RequestMapping(value = "/detail", method = { RequestMethod.POST})
    public ApiRest<SysDepartDTO> find(@RequestBody BaseIdReqDTO reqDTO) {
        // 根据传入的部门 ID，调用部门服务的获取方法获取部门实体对象
        SysDepart entity = baseService.getById(reqDTO.getId());
        // 创建一个新的部门数据传输对象
        SysDepartDTO dto = new SysDepartDTO();
        // 将部门实体对象的属性复制到部门数据传输对象中
        BeanUtils.copyProperties(entity, dto);
        return super.success(dto);
    }

    /**
     * 分页查找部门信息
     * @param reqDTO 分页请求数据传输对象，包含分页查询的条件和参数
     * @return 封装了分页查询结果的 API 统一响应对象
     */
    @RequiresRoles("sa")
    @ApiOperation(value = "分页查找")
    @RequestMapping(value = "/paging", method = { RequestMethod.POST})
    public ApiRest<IPage<SysDepartTreeDTO>> paging(@RequestBody PagingReqDTO<SysDepartDTO> reqDTO) {

        // 调用部门服务的分页查询方法，进行分页查询并将结果转换为树状数据传输对象
        IPage<SysDepartTreeDTO> page = baseService.paging(reqDTO);

        return super.success(page);
    }

    /**
     * 查找部门列表，每次最多返回 200 条数据
     * @param reqDTO 部门信息数据传输对象，包含查询部门列表的条件
     * @return 封装了部门列表信息的 API 统一响应对象
     */
    @RequiresRoles("sa")
    @ApiOperation(value = "查找列表")
    @RequestMapping(value = "/list", method = { RequestMethod.POST})
    public ApiRest<List<SysDepartDTO>> list(@RequestBody SysDepartDTO reqDTO) {

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

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

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

        return super.success(dtoList);
    }


    /**
     * 获取部门树列表
     * @return 封装了部门树列表信息的 API 统一响应对象
     */
    @RequiresRoles("sa")
    @ApiOperation(value = "树列表")
    @RequestMapping(value = "/tree", method = { RequestMethod.POST})
    public ApiRest<List<SysDepartTreeDTO>> tree() {
        // 调用部门服务的查找树列表方法，获取部门树列表数据传输对象列表
        List<SysDepartTreeDTO> dtoList = baseService.findTree();
        return super.success(dtoList);
    }


    /**
     * 对部门进行分类排序
     * @param reqDTO 部门排序请求数据传输对象，包含要排序的部门 ID 和排序值
     * @return 封装了操作结果的 API 统一响应对象
     */
    @RequiresRoles("sa")
    @ApiOperation(value = "分类排序")
    @RequestMapping(value = "/sort", method = { RequestMethod.POST})
    public ApiRest sort(@RequestBody DepartSortReqDTO reqDTO) {
        // 调用部门服务的排序方法，根据传入的部门 ID 和排序值对部门进行排序
        baseService.sort(reqDTO.getId(), reqDTO.getSort());
        return super.success();
    }
}