package org.xyzh.api.ai.service;

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

import org.springframework.web.multipart.MultipartFile;
import org.xyzh.api.ai.dto.TbKnowledge;
import org.xyzh.api.ai.dto.TbKnowledgeFile;
import org.xyzh.api.ai.vo.KnowledgeFileVO;
import org.xyzh.common.core.domain.ResultDomain;
import org.xyzh.common.core.page.PageParam;
import org.xyzh.common.core.page.PageRequest;

public interface KnowledgeService {

    // ================================= 知识库管理 =================================

    /**
     * @description    创建知识库基础信息，包含dify知识库各种参数的配置
     * @param    knowledge 知识库信息
     * @param    deptIds 部门ID列表（DEPARTMENT类型需要）
     * @param    roleIds 角色ID列表（ROLE/PRIVATE类型需要）
     * @return    ResultDomain<TbKnowledge> 创建结果
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledge> createKnowledge(TbKnowledge knowledge);

    /**
     * @description    内部创建知识库（不检查登录状态，用于系统初始化）
     * @param    knowledge 知识库信息（需要包含knowledgeId和creator）
     * @return    ResultDomain<TbKnowledge> 创建结果
     * @author    yslg
     * @since 2025-12-20
     */
    ResultDomain<TbKnowledge> createKnowledgeInternal(TbKnowledge knowledge);

    /**
     * @description    更新知识库，包含dify知识库各种参数的配置
     * @param    knowledge 知识库信息
     * @return    ResultDomain<TbKnowledge> 更新结果
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledge> updateKnowledge(TbKnowledge knowledge);

    /**
     * @description    删除知识库，同时删除dify知识库
     * @param    knowledgeId 知识库ID
     * @return    ResultDomain<Boolean> 删除结果
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<Boolean> deleteKnowledge(String knowledgeId);

    /**
     * @description    获取知识库详情，包含dify知识库各种参数的配置
     * @param    knowledgeId 知识库ID
     * @return    ResultDomain<TbKnowledge> 知识库信息
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledge> getKnowledgeById(String knowledgeId);

    /**
     * @description    查询知识库列表
     * @param    filter 过滤条件
     * @return    ResultDomain<TbKnowledge> 知识库列表
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledge> listKnowledges(TbKnowledge filter);

    /**
     * @description    分页查询知识库
     * @param    filter 过滤条件
     * @param    pageParam 分页参数
     * @return    ResultDomain<TbKnowledge> 分页结果
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledge> pageKnowledges(TbKnowledge filter, PageParam pageParam);

    /**
     * @description    获取知识库统计信息（从Dify同步文档数量和分段数量）
     * @param    knowledgeId 知识库ID
     * @return    ResultDomain<TbKnowledge> 统计信息
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledge> getKnowledgeStats(String knowledgeId);

    /**
     * @description    获取可用的嵌入模型列表
     * @return    ResultDomain<Map<String, Object>> 嵌入模型列表
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<Map<String, Object>> getAvailableEmbeddingModels();

    /**
     * @description    获取可用的Rerank模型列表
     * @return    ResultDomain<Map<String, Object>> Rerank模型列表
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<Map<String, Object>> getAvailableRerankModels();

    // ================================= 文件管理 =================================

    /**
     * @description    获取知识库文档列表（查询本地数据库，关联文件详细信息）
     * @param    pageRequest 分页请求，filter 中包含 knowledgeId
     * @return    ResultDomain<KnowledgeFileVO> 文档列表（含文件详细信息）
     * @author    yslg
     * @since 2025-12-20
     */
    ResultDomain<KnowledgeFileVO> getDocumentList(PageRequest<TbKnowledgeFile> pageRequest);

    /**
     * @description    上传文件到知识库（完整流程：minio + Dify + 数据库）
     * @param    knowledgeId 知识库ID
     * @param    file 上传的文件
     * @param    indexingTechnique 索引方式
     * @return    ResultDomain<TbKnowledgeFile> 上传结果
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledgeFile> uploadKnowledgeFile(String knowledgeId, MultipartFile file, String indexingTechnique);

    /**
     * @description    批量上传文件到知识库
     * @param    knowledgeId 知识库ID
     * @param    files 文件列表
     * @param    indexingTechnique 索引方式
     * @return    ResultDomain<TbKnowledgeFile> 上传结果
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledgeFile> batchUploadKnowledgeFile(String knowledgeId, List<MultipartFile> files, String indexingTechnique);

    /**
     * @description    上传新版本文件（fileRootId一致，version递增）
     * @param    knowledgeId 知识库ID
     * @param    file 新文件
     * @param    fileRootId 文件根ID
     * @return    ResultDomain<TbKnowledgeFile> 新版本文件信息
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<TbKnowledgeFile> updateKnowledgeFileVersion(String knowledgeId, MultipartFile file, String fileRootId);

    /**
     * @description    删除知识库文件（根据fileRootId删除所有版本）
     * @param    fileRootId 文件根ID
     * @return    ResultDomain<Boolean> 删除结果
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<Boolean> deleteKnowledgeFileById(String fileRootId);

    /**
     * @description    获取文件历史版本
     * @param    fileRootId 文件根ID
     * @return    ResultDomain<KnowledgeFileVO> 文件历史版本列表（dataList）
     * @author    yslg
     * @since 2025-12-18
     */
    ResultDomain<KnowledgeFileVO> getKnowledgeFileHistory(String fileRootId);

}
