// service 层通常负责业务逻辑处理，是控制器层(Controller)和数据访问层(Mapper)之间的桥梁
package com.aurora.service;
// 导入文章相关的数据传输对象(DTO)，用于在不同层之间传输数据
import com.aurora.model.dto.*;
import com.aurora.entity.Article;// 导入文章实体类(Article)，与数据库中的文章表相对应
import com.aurora.model.vo.*;// 导入值对象(VO)，用于接收前端传递的参数
import com.baomidou.mybatisplus.extension.service.IService;// 导入 MyBatis-Plus 的服务接口，提供了通用的服务层方法
// 导入 Java 集合框架中的 List 接口，用于返回多个文章的集合或ID列表
import java.util.List;
// 定义文章服务接口，继承自 MyBatis-Plus 的 IService 接口，并指定泛型为 Article 实体类
// 继承 IService 后，自动获得了通用的 CRUD 操作方法，如 save、remove、update、get 等
public interface ArticleService extends IService<Article> {
    // 获取置顶和推荐文章列表（通常用于首页展示）
    // 返回 TopAndFeaturedArticlesDTO 对象，包含置顶文章和推荐文章列表
    TopAndFeaturedArticlesDTO listTopAndFeaturedArticles();
    // 分页获取所有文章列表（用于文章列表页）
    // 返回 PageResultDTO<ArticleCardDTO> 分页结果，包含文章卡片信息列表
    PageResultDTO<ArticleCardDTO> listArticles();
    // 根据分类ID分页获取文章列表
    // categoryId: 分类ID，用于筛选指定分类下的文章
    // 返回分页的文章卡片列表
    PageResultDTO<ArticleCardDTO> listArticlesByCategoryId(Integer categoryId);
    // 根据文章ID获取单个文章详情（用于文章详情页）
    // articleId: 文章主键ID
    // 返回 ArticleDTO 对象，包含文章的完整内容及关联信息
    ArticleDTO getArticleById(Integer articleId);
    // 校验文章访问密码（用于访问受密码保护的文章）
    // articlePasswordVO: 包含文章ID和访问密码的值对象
    // 无返回值，通常通过抛出异常来处理密码错误的情况
    void accessArticle(ArticlePasswordVO articlePasswordVO);
    // 根据标签ID分页获取文章列表
    // tagId: 标签ID，用于筛选带有指定标签的文章
    // 返回分页的文章卡片列表
    PageResultDTO<ArticleCardDTO> listArticlesByTagId(Integer tagId);
    // 获取文章归档列表（按时间分组，如按年月归档）
    // 返回分页的 ArchiveDTO 列表，包含归档时间和对应的文章列表
    PageResultDTO<ArchiveDTO> listArchives();
    // 获取后台文章管理列表（管理员功能，支持条件查询和分页）
    // conditionVO: 封装查询条件的值对象，如关键词、状态、时间范围等
    // 返回分页的 ArticleAdminDTO 列表，包含文章的管理信息
    PageResultDTO<ArticleAdminDTO> listArticlesAdmin(ConditionVO conditionVO);
    // 保存或更新文章（根据ID判断是新增还是修改）
    // articleVO: 包含文章信息的值对象，用于接收前端传递的数据
    // 无返回值，操作结果通过异常或日志处理
    void saveOrUpdateArticle(ArticleVO articleVO);
    // 更新文章的置顶和推荐状态
    // articleTopFeaturedVO: 包含文章ID和置顶、推荐状态的值对象
    // 无返回值，直接更新数据库中的文章状态字段
    void updateArticleTopAndFeatured(ArticleTopFeaturedVO articleTopFeaturedVO);
    // 更新文章的删除状态（逻辑删除，非物理删除）
    // deleteVO: 包含文章ID和删除状态的值对象
    // 无返回值，通过更新文章的删除标记字段实现软删除
    void updateArticleDelete(DeleteVO deleteVO);
    // 物理删除文章（从数据库中彻底删除）
    // articleIds: 文章ID列表，支持批量删除
    // 无返回值，直接删除数据库中的文章记录
    void deleteArticles(List<Integer> articleIds);
    // 根据文章ID获取后台管理所需的文章详情（可能包含更多管理字段）
    // articleId: 文章主键ID
    // 返回 ArticleAdminViewDTO 对象，包含文章详情及管理信息
    ArticleAdminViewDTO getArticleByIdAdmin(Integer articleId);
    // 导出文章（通常导出为特定格式的文件，如Markdown、PDF等）
    // articleIdList: 需要导出的文章ID列表
    // 返回字符串列表，可能包含导出文件的路径或导出内容的标识
    List<String> exportArticles(List<Integer> articleIdList);
    // 根据搜索条件查询文章列表（用于搜索功能）
    // condition: 包含搜索关键词等条件的值对象
    // 返回 ArticleSearchDTO 列表，包含文章的搜索相关信息
    List<ArticleSearchDTO> listArticlesBySearch(ConditionVO condition);

}