package com.seer.teach.teacher.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.seer.teach.teacher.common.req.AppBookReadReq;
import com.seer.teach.teacher.common.resp.AppChapterInfoResp;
import com.seer.teach.teacher.common.resp.AudioData;
import com.seer.teach.teacher.common.resp.BookHistoryResp;
import com.seer.teach.teacher.module.entity.BooksEntity;
import com.seer.teach.teacher.module.entity.ReadingRecordsEntity;
import com.seer.teach.teacher.module.entity.TreasuryBoxArticlesEntity;

import jakarta.validation.constraints.NotNull;
import java.util.List;

/**
 * 阅读书籍服务接口
 * 提供用户阅读记录、书籍信息等相关业务功能
 */
public interface ReadBookService {

    /**
     * 获取当前用户的阅读历史记录
     *
     * @return BookHistoryResp 用户的阅读历史响应对象，包含历史记录详细信息
     */
    BookHistoryResp getUserHistory();

    /**
     * 根据用户ID分页获取最新的阅读记录
     *
     * @param page   分页对象，用于封装分页参数和结果
     * @param userId 用户ID
     * @return Page<ReadingRecordsEntity> 分页后的阅读记录列表
     */
    Page<ReadingRecordsEntity> getLatestReadingByUser(Page<ReadingRecordsEntity> page, Integer userId);

    /**
     * 根据书籍ID列表批量获取书籍信息
     *
     * @param bookIds 书籍ID列表
     * @return List<BooksEntity> 书籍实体列表
     */
    List<BooksEntity> getBookByIds(List<Integer> bookIds);

    /**
     * 获取当前用户阅读的书籍总数
     *
     * @return Integer 用户阅读的书籍数量
     */
    Integer getUserBookCount();

    /**
     * 分页查询健康知识文章列表
     * @param page 分页参数对象，包含当前页码和每页大小等信息
     * @return 返回分页后的健康知识文章实体列表
     */
    IPage<TreasuryBoxArticlesEntity> healthKnowPage(IPage<TreasuryBoxArticlesEntity> page);

    /**
     * 分页查询编程相关文章列表
     * @param page 分页参数对象，包含当前页码和每页大小等信息
     * @return 返回分页后的编程文章实体列表
     */
    IPage<TreasuryBoxArticlesEntity> programming(IPage<TreasuryBoxArticlesEntity> page);

    /**
     * 根据ID获取章节信息
     * @param id 文章或章节的唯一标识符
     * @return 返回指定ID对应的章节详细信息响应对象
     */
    AppChapterInfoResp chapters(Integer id);

    /**
     * 读取音频数据列表
     *
     * @param params 应用书籍阅读请求参数对象，包含阅读相关配置信息
     * @return 音频数据列表，返回与请求参数匹配的音频数据集合
     */
    List<AudioData> read(AppBookReadReq params);
}
