package org.xyzh.api.ai.statistics;

import org.xyzh.common.core.domain.ResultDomain;
import org.xyzh.common.dto.ai.TbAiUsageStatistics;

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

/**
 * @description AI使用统计服务接口
 * @filename AiUsageStatisticsService.java
 * @author yslg
 * @copyright xyzh
 * @since 2025-10-15
 */
public interface AiUsageStatisticsService {

    /**
     * @description 获取用户使用统计
     * @param userID 用户ID
     * @param startDate 开始日期（可选）
     * @param endDate 结束日期（可选）
     * @return ResultDomain<TbAiUsageStatistics> 统计列表
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> getUserStatistics(String userID, Date startDate, Date endDate);

    /**
     * @description 获取指定日期的使用统计
     * @param userID 用户ID
     * @param statDate 统计日期
     * @return ResultDomain<TbAiUsageStatistics> 统计信息
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> getDailyStatistics(String userID, Date statDate);

    /**
     * @description 创建或更新使用统计
     * @param statistics 统计信息
     * @return ResultDomain<TbAiUsageStatistics> 创建/更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> saveStatistics(TbAiUsageStatistics statistics);

    /**
     * @description 更新使用统计
     * @param userID 用户ID
     * @param statDate 统计日期
     * @param conversationCount 会话数量
     * @param messageCount 消息数量
     * @param totalTokens 总Token数
     * @param fileCount 文件数量
     * @return ResultDomain<TbAiUsageStatistics> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> updateStatistics(String userID, Date statDate, Integer conversationCount, 
                                                       Integer messageCount, Integer totalTokens, Integer fileCount);

    /**
     * @description 增加会话数量
     * @param userID 用户ID
     * @param statDate 统计日期
     * @return ResultDomain<TbAiUsageStatistics> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> incrementConversationCount(String userID, Date statDate);

    /**
     * @description 增加消息数量
     * @param userID 用户ID
     * @param statDate 统计日期
     * @param tokenCount Token数量
     * @return ResultDomain<TbAiUsageStatistics> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> incrementMessageCount(String userID, Date statDate, Integer tokenCount);

    /**
     * @description 增加文件数量
     * @param userID 用户ID
     * @param statDate 统计日期
     * @return ResultDomain<TbAiUsageStatistics> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> incrementFileCount(String userID, Date statDate);

    /**
     * @description 获取使用排行榜
     * @param statDate 统计日期
     * @param limit 限制数量
     * @return ResultDomain<TbAiUsageStatistics> 排行榜
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> getUsageRanking(Date statDate, Integer limit);

    /**
     * @description 获取总体使用统计
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return ResultDomain<TbAiUsageStatistics> 总体统计
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> getOverallStatistics(Date startDate, Date endDate);

    /**
     * @description 获取用户使用趋势
     * @param userID 用户ID
     * @param days 天数
     * @return ResultDomain<TbAiUsageStatistics> 趋势数据
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> getUserUsageTrend(String userID, Integer days);

    /**
     * @description 删除使用统计
     * @param statisticsID 统计ID
     * @return ResultDomain<Boolean> 删除结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<Boolean> deleteStatistics(String statisticsID);

    /**
     * @description 获取用户Token使用统计
     * @param userID 用户ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return ResultDomain<TbAiUsageStatistics> Token统计
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiUsageStatistics> getUserTokenStatistics(String userID, Date startDate, Date endDate);
}
