package org.xyzh.api.ai.history;

import org.xyzh.common.core.domain.ResultDomain;
import org.xyzh.common.core.page.PageDomain;
import org.xyzh.common.core.page.PageParam;
import org.xyzh.common.dto.ai.TbAiConversation;
import org.xyzh.common.dto.ai.TbAiMessage;

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

/**
 * @description AI对话历史服务接口
 * @filename AiChatHistoryService.java
 * @author AI Assistant
 * @copyright xyzh
 * @since 2025-11-04
 */
public interface AiChatHistoryService {

    /**
     * 分页查询用户的会话列表
     * @param agentId 智能体ID（可选）
     * @param keyword 关键词搜索（标题、摘要）
     * @param isFavorite 是否收藏（可选）
     * @param startDate 开始日期（可选）
     * @param endDate 结束日期（可选）
     * @param pageParam 分页参数
     * @return 会话列表分页结果
     */
    PageDomain<TbAiConversation> pageUserConversations(
            String agentId,
            String keyword,
            Boolean isFavorite,
            Date startDate,
            Date endDate,
            PageParam pageParam
    );

    /**
     * 搜索会话（全文搜索标题和摘要）
     * @param keyword 搜索关键词
     * @param pageParam 分页参数
     * @return 会话列表
     */
    PageDomain<TbAiConversation> searchConversations(String keyword, PageParam pageParam);

    /**
     * 搜索消息内容（全文搜索）
     * @param keyword 搜索关键词
     * @param conversationId 会话ID（可选，限定范围）
     * @param pageParam 分页参数
     * @return 消息列表
     */
    PageDomain<TbAiMessage> searchMessages(String keyword, String conversationId, PageParam pageParam);

    /**
     * 收藏/取消收藏会话
     * @param conversationId 会话ID
     * @param isFavorite 是否收藏
     * @return 操作结果
     */
    ResultDomain<Boolean> toggleFavorite(String conversationId, Boolean isFavorite);

    /**
     * 置顶/取消置顶会话
     * @param conversationId 会话ID
     * @param isPinned 是否置顶
     * @return 操作结果
     */
    ResultDomain<Boolean> togglePin(String conversationId, Boolean isPinned);

    /**
     * 批量删除会话
     * @param conversationIds 会话ID列表
     * @return 删除结果
     */
    ResultDomain<Integer> batchDeleteConversations(List<String> conversationIds);

    /**
     * 获取用户的对话统计信息
     * @param userId 用户ID（可选，默认当前用户）
     * @return 统计信息
     */
    ResultDomain<Map<String, Object>> getUserChatStatistics(String userId);

    /**
     * 获取会话的详细统计
     * @param conversationId 会话ID
     * @return 统计信息（消息数、Token数、评分分布等）
     */
    ResultDomain<Map<String, Object>> getConversationStatistics(String conversationId);

    /**
     * 导出会话记录（Markdown格式）
     * @param conversationId 会话ID
     * @return Markdown文本
     */
    ResultDomain<String> exportConversationAsMarkdown(String conversationId);

    /**
     * 导出会话记录（JSON格式）
     * @param conversationId 会话ID
     * @return JSON文本
     */
    ResultDomain<String> exportConversationAsJson(String conversationId);

    /**
     * 批量导出会话
     * @param conversationIds 会话ID列表
     * @param format 格式（markdown/json）
     * @return 导出内容
     */
    ResultDomain<String> batchExportConversations(List<String> conversationIds, String format);

    /**
     * 清理过期会话（软删除超过N天的会话）
     * @param days 天数
     * @return 清理数量
     */
    ResultDomain<Integer> cleanExpiredConversations(Integer days);

    /**
     * 获取用户最近的对话
     * @param limit 数量限制
     * @return 会话列表
     */
    ResultDomain<TbAiConversation> getRecentConversations(Integer limit);

    /**
     * 获取热门会话（基于消息数或Token数）
     * @param limit 数量限制
     * @return 会话列表
     */
    ResultDomain<TbAiConversation> getPopularConversations(Integer limit);
}

