package com.dora.service;

import com.dora.dto.UvStatisticsDto;

import java.time.LocalDate;
import java.util.List;

/**
 * UV统计服务接口
 * 用于网站访问量统计和分析
 * 
 * @author dora
 * @date 2024/12/01
 */
public interface UvStatisticsService {

    /**
     * 记录访问IP
     * 
     * @param ip 访问者IP地址
     * @param userAgent 用户代理信息
     * @return 是否为新访客（今日首次访问）
     */
    boolean recordVisit(String ip, String userAgent);

    /**
     * 获取指定日期的UV数据
     * 
     * @param date 日期
     * @return UV统计数据
     */
    UvStatisticsDto getUvByDate(LocalDate date);

    /**
     * 获取最近7天的UV数据
     * 
     * @return UV统计数据列表
     */
    List<UvStatisticsDto> getRecentSevenDaysUv();

    /**
     * 获取今日UV数据
     * 
     * @return 今日UV统计数据
     */
    UvStatisticsDto getTodayUv();

    /**
     * 获取UV统计汇总信息
     * 
     * @return UV汇总统计
     */
    UvStatisticsDto.UvSummary getUvSummary();

    /**
     * 清理过期的UV数据
     * 清理7天前的数据
     */
    void cleanExpiredUvData();
}
