package org.xyzh.api.ai.message;

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


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

    /**
     * @description 获取会话消息列表
     * @param conversationID 会话ID
     * @param limit 限制数量（可选）
     * @return ResultDomain<TbAiMessage> 消息列表
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> getConversationMessages(String conversationID, Integer limit);

    /**
     * @description 根据ID获取消息详情
     * @param messageID 消息ID
     * @return ResultDomain<TbAiMessage> 消息详情
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> getMessageById(String messageID);

    /**
     * @description 发送用户消息
     * @param conversationID 会话ID
     * @param userID 用户ID
     * @param content 消息内容
     * @param fileIDs 关联文件ID（可选）
     * @return ResultDomain<TbAiMessage> 创建结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> sendUserMessage(String conversationID, String userID, String content, String fileIDs);

    /**
     * @description 发送助手消息
     * @param conversationID 会话ID
     * @param userID 用户ID
     * @param content 消息内容
     * @param knowledgeIDs 引用知识ID（可选）
     * @param tokenCount Token数量
     * @return ResultDomain<TbAiMessage> 创建结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> sendAssistantMessage(String conversationID, String userID, String content, String knowledgeIDs, Integer tokenCount);

    /**
     * @description 发送系统消息
     * @param conversationID 会话ID
     * @param content 消息内容
     * @return ResultDomain<TbAiMessage> 创建结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> sendSystemMessage(String conversationID, String content);

    /**
     * @description 更新消息内容
     * @param messageID 消息ID
     * @param content 新内容
     * @return ResultDomain<TbAiMessage> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> updateMessageContent(String messageID, String content);

    /**
     * @description 更新消息Token数量
     * @param messageID 消息ID
     * @param tokenCount Token数量
     * @return ResultDomain<TbAiMessage> 更新结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> updateMessageTokens(String messageID, Integer tokenCount);

    /**
     * @description 删除消息
     * @param messageID 消息ID
     * @return ResultDomain<Boolean> 删除结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<Boolean> deleteMessage(String messageID);

    /**
     * @description 清空会话消息
     * @param conversationID 会话ID
     * @return ResultDomain<Boolean> 清空结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<Boolean> clearConversationMessages(String conversationID);

    /**
     * @description 获取用户消息统计
     * @param userID 用户ID
     * @param conversationID 会话ID（可选）
     * @return ResultDomain<TbAiMessage> 消息统计
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> getUserMessageStats(String userID, String conversationID);

    /**
     * @description 获取会话最后一条消息
     * @param conversationID 会话ID
     * @return ResultDomain<TbAiMessage> 最后消息
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> getLastMessage(String conversationID);

    /**
     * @description 搜索消息内容
     * @param userID 用户ID
     * @param keyword 关键词
     * @param conversationID 会话ID（可选）
     * @return ResultDomain<TbAiMessage> 搜索结果
     * @author yslg
     * @since 2025-10-15
     */
    ResultDomain<TbAiMessage> searchMessages(String userID, String keyword, String conversationID);
}
