package org.xyzh.api.ai.conversation;

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

import java.util.Date;

/**
 * @description AI对话会话服务接口
 * @filename AiConversationService.java
 * @author yslg
 * @copyright xyzh
 * @since 2025-10-15
 */
public interface AiConversationService {

    /**
     * @description 获取用户会话列表
     * @param userID 用户ID
     * @param status 状态（可选）
     * @return ResultDomain<TbAiConversation> 会话列表
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> getUserConversations(String userID, Integer status);

    /**
     * @description 根据ID获取会话详情
     * @param conversationID 会话ID
     * @return ResultDomain<TbAiConversation> 会话详情
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> getConversationById(String conversationID);

    /**
     * @description 创建新会话
     * @param userID 用户ID
     * @param title 会话标题
     * @return ResultDomain<TbAiConversation> 创建结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> createConversation(String userID, String title);

    /**
     * @description 更新会话标题
     * @param conversationID 会话ID
     * @param title 新标题
     * @return ResultDomain<TbAiConversation> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> updateConversationTitle(String conversationID, String title);

    /**
     * @description 更新会话状态
     * @param conversationID 会话ID
     * @param status 状态
     * @return ResultDomain<TbAiConversation> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> updateConversationStatus(String conversationID, Integer status);

    /**
     * @description 结束会话
     * @param conversationID 会话ID
     * @return ResultDomain<TbAiConversation> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> endConversation(String conversationID);

    /**
     * @description 删除会话
     * @param conversationID 会话ID
     * @return ResultDomain<Boolean> 删除结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<Boolean> deleteConversation(String conversationID);

    /**
     * @description 更新会话消息统计
     * @param conversationID 会话ID
     * @param messageCount 消息数量
     * @param lastMessageTime 最后消息时间
     * @return ResultDomain<TbAiConversation> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> updateConversationStats(String conversationID, Integer messageCount, Date lastMessageTime);

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

    /**
     * @description 清空用户所有会话
     * @param userID 用户ID
     * @return ResultDomain<Boolean> 清空结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<Boolean> clearUserConversations(String userID);

    /**
     * @description 获取最近会话
     * @param userID 用户ID
     * @param limit 限制数量
     * @return ResultDomain<TbAiConversation> 最近会话列表
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiConversation> getRecentConversations(String userID, Integer limit);
}
