package org.xyzh.study.service;

import org.xyzh.api.study.history.LearningHistoryAPI;
import org.xyzh.common.core.domain.ResultDomain;
import org.xyzh.common.core.page.PageDomain;
import org.xyzh.common.core.page.PageRequest;
import org.xyzh.common.dto.study.TbLearningHistory;
import org.xyzh.common.vo.LearningHistoryVO;
import org.xyzh.common.vo.LearningStatisticsVO;

import java.util.Date;
import java.util.List;

/**
 * @description 学习历史服务接口
 * @filename SCLearningHistoryService.java
 * @author yslg
 * @copyright xyzh
 * @since 2025-10-27
 */
public interface SCLearningHistoryService extends LearningHistoryAPI {

    /**
     * @description 查询学习历史列表
     * @param filter 过滤条件
     * @return ResultDomain<LearningHistoryVO> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<LearningHistoryVO> getLearningHistories(TbLearningHistory filter);

    /**
     * @description 分页查询学习历史
     * @param pageRequest 分页查询请求
     * @return ResultDomain<PageDomain<LearningHistoryVO>> 分页结果
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<PageDomain<LearningHistoryVO>> getLearningHistoriesPage(PageRequest<TbLearningHistory> pageRequest);

    /**
     * @description 根据ID查询学习历史
     * @param id 历史记录ID
     * @return ResultDomain<TbLearningHistory> 学习历史
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<TbLearningHistory> getLearningHistoryById(String id);

    /**
     * @description 获取用户某时间段的学习统计
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return ResultDomain<LearningStatisticsVO> 学习统计
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<LearningStatisticsVO> getUserLearningStatistics(String userId, Date startTime, Date endTime);

    /**
     * @description 获取用户某时间段的学习统计（按周期）
     * @param userId 用户ID
     * @param periodType 周期类型（day/week/month）
     * @return ResultDomain<LearningStatisticsVO> 学习统计
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<LearningStatisticsVO> getUserLearningStatisticsByPeriod(String userId, String periodType);

    /**
     * @description 获取当前用户的学习历史
     * @param filter 过滤条件
     * @return ResultDomain<LearningHistoryVO> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<LearningHistoryVO> getCurrentUserLearningHistories(TbLearningHistory filter);

    /**
     * @description 获取当前用户的学习统计
     * @param periodType 周期类型（day/week/month）
     * @return ResultDomain<LearningStatisticsVO> 学习统计
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<LearningStatisticsVO> getCurrentUserLearningStatistics(String periodType);

    /**
     * @description 删除学习历史
     * @param id 历史记录ID
     * @return ResultDomain<Boolean> 删除结果
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<Boolean> deleteLearningHistory(String id);

    /**
     * @description 批量删除学习历史
     * @param ids 历史记录ID列表
     * @return ResultDomain<Boolean> 删除结果
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<Boolean> batchDeleteLearningHistories(List<String> ids);

    /**
     * @description 获取用户最近的学习历史
     * @param userId 用户ID
     * @param limit 限制数量
     * @return ResultDomain<LearningHistoryVO> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    ResultDomain<LearningHistoryVO> getRecentLearningHistories(String userId, Integer limit);
}

