package com.emotion.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.emotion.common.BasePageRequest;
import com.emotion.common.PageResult;
import com.emotion.dto.request.guest.GuestUserCreateRequest;
import com.emotion.dto.request.guest.GuestUserUpdateRequest;
import com.emotion.dto.response.guest.GuestUserResponse;
import com.emotion.entity.GuestUser;

import java.time.LocalDateTime;
import java.util.List;

/**
 * 访客用户服务接口
 * 
 * @author huazhongmin
 * @date 2025-09-08
 */
public interface GuestUserService extends IService<GuestUser> {
    
    /**
     * 分页查询访客用户
     */
    IPage<GuestUser> getPage(BasePageRequest request);
    
    /**
     * 分页查询访客用户响应
     */
    PageResult<GuestUserResponse> getPageWithResponse(BasePageRequest request);

    /**
     * 根据ID获取访客用户响应
     */
    GuestUserResponse getGuestUserResponseById(String id);

    /**
     * 根据设备ID查询访客用户
     */
    GuestUser getByDeviceId(String deviceId);
    
    /**
     * 根据IP地址查询访客用户
     */
    List<GuestUser> getByIpAddress(String ipAddress);
    
    /**
     * 根据用户代理查询访客用户
     */
    List<GuestUser> getByUserAgent(String userAgent);
    
    /**
     * 根据状态查询访客用户
     */
    List<GuestUser> getByStatus(String status);
    
    /**
     * 根据时间范围查询访客用户
     */
    List<GuestUser> getByTimeRange(LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 根据最后活跃时间范围查询访客用户
     */
    List<GuestUser> getByLastActiveTimeRange(LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 统计指定状态的访客用户数量
     */
    Long countByStatus(String status);
    
    /**
     * 统计指定IP地址的访客用户数量
     */
    Long countByIpAddress(String ipAddress);
    
    /**
     * 统计今日新增访客用户
     */
    Long countTodayNewGuests();
    
    /**
     * 统计活跃访客用户
     */
    Long countActiveGuests(Integer days);
    
    /**
     * 查询最近访问的访客用户
     */
    List<GuestUser> getRecentVisitors(Integer limit);
    
    /**
     * 查询长时间未活跃的访客用户
     */
    List<GuestUser> getInactiveGuests(Integer days);
    
    /**
     * 根据访问次数范围查询访客用户
     */
    List<GuestUser> getByVisitCountRange(Integer minVisits, Integer maxVisits);
    
    /**
     * 查询平均访问次数
     */
    Double getAvgVisitCount();
    
    /**
     * 更新访客用户最后活跃时间
     */
    boolean updateLastActiveTime(String id, LocalDateTime lastActiveTime);
    
    /**
     * 更新访客用户访问次数
     */
    boolean incrementVisitCount(String id);
    
    /**
     * 更新访客用户状态
     */
    boolean updateStatus(String id, String status);
    
    /**
     * 根据设备信息查询或创建访客用户
     */
    GuestUser getOrCreateByDeviceInfo(String deviceId, String ipAddress, String userAgent);
    
    /**
     * 清理过期的访客用户数据
     */
    boolean cleanExpiredGuests(Integer days);
    
    /**
     * 创建访客用户
     */
    GuestUser createGuestUser(String deviceId, String ipAddress, String userAgent, String location);

    /**
     * 创建访客用户并返回响应
     */
    GuestUserResponse createGuestUserWithResponse(GuestUserCreateRequest request);

    /**
     * 更新访客用户并返回响应
     */
    GuestUserResponse updateGuestUserWithResponse(GuestUserUpdateRequest request);

    /**
     * 删除访客用户
     */
    boolean deleteGuestUser(String id);
}