package org.xyzh.study.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import org.xyzh.common.core.page.PageParam;
import org.xyzh.common.dto.study.TbLearningHistory;
import org.xyzh.common.vo.LearningHistoryVO;

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

/**
 * @description 学习观看历史数据访问层
 * @filename LearningHistoryMapper.java
 * @author yslg
 * @copyright xyzh
 * @since 2025-10-27
 */
@Mapper
public interface LearningHistoryMapper extends BaseMapper<TbLearningHistory> {

    /**
     * @description 插入学习历史记录
     * @param learningHistory 学习历史
     * @return int 影响行数
     * @author yslg
     * @since 2025-10-27
     */
    int insertLearningHistory(TbLearningHistory learningHistory);

    /**
     * @description 更新学习历史记录
     * @param learningHistory 学习历史
     * @return int 影响行数
     * @author yslg
     * @since 2025-10-27
     */
    int updateLearningHistory(TbLearningHistory learningHistory);

    /**
     * @description 批量插入学习历史记录
     * @param historyList 学习历史列表
     * @return int 影响行数
     * @author yslg
     * @since 2025-10-27
     */
    int batchInsertLearningHistories(@Param("historyList") List<TbLearningHistory> historyList);

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

    /**
     * @description 根据用户ID查询学习历史列表
     * @param userId 用户ID
     * @return List<TbLearningHistory> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    List<TbLearningHistory> selectByUserId(@Param("userId") String userId);

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

    /**
     * @description 根据条件查询学习历史VO列表（带关联信息）
     * @param filter 过滤条件
     * @return List<LearningHistoryVO> 学习历史VO列表
     * @author yslg
     * @since 2025-10-27
     */
    List<LearningHistoryVO> selectLearningHistoriesWithDetails(TbLearningHistory filter);

    /**
     * @description 分页查询学习历史
     * @param filter 过滤条件
     * @param pageParam 分页参数
     * @return List<TbLearningHistory> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    List<TbLearningHistory> selectLearningHistoriesPage(@Param("filter") TbLearningHistory filter, @Param("pageParam") PageParam pageParam);

    /**
     * @description 统计学习历史总数
     * @param filter 过滤条件
     * @return long 总数
     * @author yslg
     * @since 2025-10-27
     */
    long countLearningHistories(@Param("filter") TbLearningHistory filter);

    /**
     * @description 根据时间段查询学习历史
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return List<TbLearningHistory> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    List<TbLearningHistory> selectByUserIdAndTimeRange(@Param("userId") String userId, 
                                                        @Param("startTime") Date startTime, 
                                                        @Param("endTime") Date endTime);

    /**
     * @description 根据时间段和资源类型查询学习历史
     * @param userId 用户ID
     * @param resourceType 资源类型
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return List<TbLearningHistory> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    List<TbLearningHistory> selectByUserIdAndResourceTypeAndTimeRange(
            @Param("userId") String userId,
            @Param("resourceType") Integer resourceType,
            @Param("startTime") Date startTime,
            @Param("endTime") Date endTime);

    /**
     * @description 统计用户某时间段的学习时长
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return Map<String, Object> 统计结果（totalDuration, learnCount等）
     * @author yslg
     * @since 2025-10-27
     */
    Map<String, Object> selectLearningStatisticsByTimeRange(
            @Param("userId") String userId,
            @Param("startTime") Date startTime,
            @Param("endTime") Date endTime);

    /**
     * @description 统计用户某时间段各资源类型的学习时长
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return List<Map<String, Object>> 统计结果列表
     * @author yslg
     * @since 2025-10-27
     */
    List<Map<String, Object>> selectLearningStatisticsByResourceType(
            @Param("userId") String userId,
            @Param("startTime") Date startTime,
            @Param("endTime") Date endTime);

    /**
     * @description 获取用户学习的资源列表（按时间段）
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return List<Map<String, Object>> 资源列表
     * @author yslg
     * @since 2025-10-27
     */
    List<Map<String, Object>> selectLearnedResourcesByTimeRange(
            @Param("userId") String userId,
            @Param("startTime") Date startTime,
            @Param("endTime") Date endTime);

    /**
     * @description 删除学习历史（软删除）
     * @param id 历史记录ID
     * @return int 影响行数
     * @author yslg
     * @since 2025-10-27
     */
    int deleteLearningHistory(@Param("id") String id);

    /**
     * @description 批量删除学习历史（软删除）
     * @param ids 历史记录ID列表
     * @return int 影响行数
     * @author yslg
     * @since 2025-10-27
     */
    int batchDeleteLearningHistories(@Param("ids") List<String> ids);

    /**
     * @description 根据会话ID查询学习历史
     * @param sessionId 会话ID
     * @return List<TbLearningHistory> 学习历史列表
     * @author yslg
     * @since 2025-10-27
     */
    List<TbLearningHistory> selectBySessionId(@Param("sessionId") String sessionId);

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

