package org.xyzh.api.ai.knowledge;

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.TbAiKnowledge;

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

/**
 * @description AI知识库管理服务接口
 * @filename AiKnowledgeService.java
 * @author AI Assistant
 * @copyright xyzh
 * @since 2025-11-04
 */
public interface AiKnowledgeService {

    /**
     * 创建知识库（同步到Dify）
     * @param knowledge 知识库信息
     * @param permissionType 权限类型：PUBLIC-公开，DEPARTMENT-部门，ROLE-角色，PRIVATE-私有
     * @param deptIds 部门ID列表（DEPARTMENT类型需要）
     * @param roleIds 角色ID列表（ROLE/PRIVATE类型需要）
     * @return 创建结果
     */
    ResultDomain<TbAiKnowledge> createKnowledge(
            TbAiKnowledge knowledge,
            String permissionType,
            List<String> deptIds,
            List<String> roleIds
    );

    /**
     * 更新知识库
     * @param knowledge 知识库信息
     * @return 更新结果
     */
    ResultDomain<TbAiKnowledge> updateKnowledge(TbAiKnowledge knowledge);

    /**
     * 删除知识库（同时删除Dify中的知识库）
     * @param knowledgeId 知识库ID
     * @return 删除结果
     */
    ResultDomain<Boolean> deleteKnowledge(String knowledgeId);

    /**
     * 根据ID查询知识库（带权限校验）
     * @param knowledgeId 知识库ID
     * @return 知识库信息
     */
    ResultDomain<TbAiKnowledge> getKnowledgeById(String knowledgeId);

    /**
     * 查询用户有权限的知识库列表
     * @param filter 过滤条件
     * @return 知识库列表
     */
    ResultDomain<TbAiKnowledge> listKnowledges(TbAiKnowledge filter);

    /**
     * 分页查询知识库
     * @param filter 过滤条件
     * @param pageParam 分页参数
     * @return 分页结果
     */
    ResultDomain<TbAiKnowledge> pageKnowledges(TbAiKnowledge filter, PageParam pageParam);

    /**
     * 同步Dify知识库信息到本地
     * @param knowledgeId 知识库ID
     * @return 同步结果
     */
    ResultDomain<TbAiKnowledge> syncFromDify(String knowledgeId);

    /**
     * 更新知识库权限
     * @param knowledgeId 知识库ID
     * @param permissionType 权限类型
     * @param deptIds 部门ID列表
     * @param roleIds 角色ID列表
     * @return 更新结果
     */
    ResultDomain<Boolean> updateKnowledgePermission(
            String knowledgeId,
            String permissionType,
            List<String> deptIds,
            List<String> roleIds
    );

    /**
     * 检查用户是否有知识库访问权限
     * @param knowledgeId 知识库ID
     * @param permissionType 权限类型：read/write/execute
     * @return 是否有权限
     */
    ResultDomain<Boolean> checkKnowledgePermission(String knowledgeId, String permissionType);

    /**
     * 查询知识库的文档数量和分段数量（从Dify同步）
     * @param knowledgeId 知识库ID
     * @return 统计信息
     */
    ResultDomain<TbAiKnowledge> getKnowledgeStats(String knowledgeId);

    /**
     * 获取可用的嵌入模型列表
     * @return 嵌入模型列表
     */
    ResultDomain<Map<String, Object>> getAvailableEmbeddingModels();

    /**
     * 获取可用的Rerank模型列表
     * @return Rerank模型列表
     */
    ResultDomain<Map<String, Object>> getAvailableRerankModels();

    /**
     * 获取知识库文档列表
     * @param knowledgeId 知识库ID
     * @param page 页码（从1开始）
     * @param limit 每页数量
     * @return 文档列表
     */
    ResultDomain<Map<String, Object>> getDocumentList(String knowledgeId, Integer page, Integer limit);
}
