|
|
// 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);
|
|
|
|
|
|
}
|
