package com.ruoyi.web.kb.service;

import java.io.File;

/**
 * 与大模型知识库后台的 HTTP 交互（上传文档、删除文档等），供各业务标准模块复用。
 */
public interface KnowledgeBaseClient
{
    /**
     * 方式一：multipart/form-data 上传本地文件入库。
     *
     * @param file           本地文件
     * @param uploadFilename multipart 中 file 部分的文件名
     * @param knowledgeBase  知识库标识，默认 {@code default}
     * @param category       分类
     * @return 知识库返回的 file_id
     */
    String uploadFile(File file, String uploadFilename, String knowledgeBase, String category);

    /**
     * 方式二：multipart/form-data 提交 url、category、description 上传文件入库。
     *
     * @param fileUrl     知识库可 HTTP 拉取的正文地址（对应表 content_file_url）
     * @param category    分类，如「养殖管理标准」
     * @param description 描述，一般为标准名称
     * @return 知识库返回的 file_id，写入业务表 kb_doc_id
     */
    String uploadFileByUrl(String fileUrl, String category, String description);

    /**
     * 按知识库文档 id 移出条目。
     *
     * @param kbDocId {@code /api/v1/kb/files/{id}} 中的 id
     */
    void deleteFile(String kbDocId);
}
