package com.aurora.mapper;

import com.aurora.model.dto.ArticleAdminDTO;
// 导入各种数据传输对象(DTO)，用于前台数据展示
import com.aurora.model.dto.ArticleCardDTO;
import com.aurora.model.dto.ArticleDTO;
import com.aurora.model.dto.ArticleStatisticsDTO;
import com.aurora.entity.Article;//导入和数据库对应的实体类Article,接口操作的就是这个实体类对应的数据库表
// 导入查询条件值对象
import com.aurora.model.vo.ConditionVO;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import org.apache.ibatis.annotations.Param;
import org.springframework.stereotype.Repository;

import java.util.List;


@Repository
// 定义ArticleMapper接口，继承自MyBatis-Plus的BaseMapper接口，泛型为Article实体类
// 继承BaseMapper后，自动获得了基本的CRUD（增删改查）方法，如insert、deleteById、updateById、selectById等
public interface ArticleMapper extends BaseMapper<Article> {
    // 获取置顶和推荐文章列表（通常用于前段首页卡片展示）
    // 返回ArticleCardDTO列表，包含文章卡片所需的基本信息
    List<ArticleCardDTO> listTopAndFeaturedArticles();
    // 分页获取所有文章列表
    // @Param注解给参数起别名，在XML中可以通过#{current}和#{size}引用
    // current: 当前页码，size: 每页大小（每页条数）
    List<ArticleCardDTO> listArticles(@Param("current") Long current, @Param("size") Long size);
    // 根据分类ID分页获取文章列表
    // categoryId: 分类ID，用于筛选指定分类的文章
    List<ArticleCardDTO> getArticlesByCategoryId(@Param("current") Long current, @Param("size") Long size, @Param("categoryId") Integer categoryId);
    // 根据文章ID获取单篇文章详情（包含文章完整内容等信息）
    // 返回ArticleDTO，通常比ArticleCardDTO包含更多详细信息（如文章正文）
    ArticleDTO getArticleById(@Param("articleId") Integer articleId);
    // 根据当前文章ID获取上一篇文章的卡片信息（按时间或ID排序）
    // 用于文章详情页的"上一篇"导航
    ArticleCardDTO getPreArticleById(@Param("articleId") Integer articleId);
    // 根据当前文章ID获取下一篇文章的卡片信息（按时间或ID排序）
    // 用于文章详情页的"下一篇"导航
    ArticleCardDTO getNextArticleById(@Param("articleId") Integer articleId);
    // 获取第一篇文章的卡片信息（按时间或ID排序，通常是最早的文章）
    ArticleCardDTO getFirstArticle();
    // 获取最后一篇文章的卡片信息（按时间或ID排序，通常是最新的文章）
    ArticleCardDTO getLastArticle();
    // 根据标签ID分页获取文章归档列表
    // tagId: 标签ID，用于筛选带有指定标签的文章
    List<ArticleCardDTO> listArticlesByTagId(@Param("current") Long current, @Param("size") Long size, @Param("tagId") Integer tagId);
    // 分页获取文章归档列表（通常按时间分组，如按年月）
    // 归档页面通常显示文章标题和创建时间，不显示完整内容
    List<ArticleCardDTO> listArchives(@Param("current") Long current, @Param("size") Long size);
    // 统计后台文章数量（根据查询条件）
    // conditionVO: 包含各种查询条件，如关键词、状态、时间范围等
    // 返回符合条件的文章总数，用于分页计算
    Integer countArticleAdmins(@Param("conditionVO") ConditionVO conditionVO);
    // 按条件分页查询获取后台文章列表（管理员功能）
    // 返回ArticleAdminDTO列表，可能包含更多管理字段（如状态、浏览量等）
    List<ArticleAdminDTO> listArticlesAdmin(@Param("current") Long current, @Param("size") Long size, @Param("conditionVO") ConditionVO conditionVO);
    // 获取文章统计信息（如按分类、标签、状态统计文章数量）
    // 用于后台仪表盘的数据展示
    List<ArticleStatisticsDTO> listArticleStatistics();
    //@Param("参数名")：MyBatis的注解，用于给方法参数命名，方便在对应的XML映射文件中通过#{参数名}获取参数值
}