package com.huimv.employment.integration.kb;

import com.fasterxml.jackson.databind.JsonNode;
import com.huimv.employment.integration.kb.rag.RagFileListQuery;
import com.huimv.employment.integration.kb.rag.RagRetrieveRequest;

import java.io.File;

/**
 * RAG 知识库 HTTP 客户端（前缀 {@code /api/rag}），供各业务模块复用。
 *
 * @see <a href="doc/灵活用工项目后端与智能体接口文档.md">RAG 接口文档</a>
 */
public interface KnowledgeBaseClient {

    /**
     * {@code GET /api/rag/health} 健康检查。
     */
    JsonNode health();

    /**
     * {@code POST /api/rag/files} 上传文件（异步处理）。
     *
     * @return track_id，需后续调用 {@link #getFileStatus(String)} 轮询状态
     */
    String uploadFile(File file, String uploadFilename);

    /**
     * {@code PUT /api/rag/files/{file_id}} 更新文件。
     *
     * @return track_id
     */
    String updateFile(String fileId, File file, String uploadFilename);

    /**
     * {@code GET /api/rag/files} 分页列出文档。
     */
    JsonNode listFiles(RagFileListQuery query);

    /**
     * {@code GET /api/rag/files/{file_id}} 查询处理状态（track_id 或 doc_id）。
     * <p>status：processing / processed / failed</p>
     */
    JsonNode getFileStatus(String fileId);

    /**
     * {@code DELETE /api/rag/files/{file_id}} 删除单个文档。
     */
    void deleteFile(String fileId);

    /**
     * {@code POST /api/rag/retrieve} 语义检索。
     */
    JsonNode retrieve(RagRetrieveRequest request);

    /**
     * {@code POST /api/rag/insert-text} 插入单条文本。
     *
     * @return track_id
     */
    String insertText(String text, String fileSource);

    /**
     * {@code POST /api/rag/reprocess-failed} 重新处理失败文档。
     */
    JsonNode reprocessFailed();
}
