package com.agent.management.service;

import org.springframework.ai.document.Document;

import java.util.List;

/**
 * 向量库操作服务（Milvus 封装）
 *
 * <p>当 app.milvus.enabled=false 时，{@link org.springframework.ai.vector.store.VectorStore}
 * bean 不会被创建，所有调用抛出 {@link com.agent.management.common.exception.BusinessException}。</p>
 *
 * <p>Spring AI 的 {@code VectorStore.add(List<Document>)} 会内部调用 EmbeddingModel 完成向量化，
 * 因此调用方只需传入 Document 列表即可（Document 的 id 将作为 Milvus 主键）。</p>
 */
public interface VectorStoreService {

    /**
     * 批量入库：传入 Document 列表（含 id/text/metadata），VectorStore 内部 embedding 后写入 Milvus
     *
     * @param documents 已分配 id 的文档列表
     * @return 与入参顺序一致的 id 列表（即 Milvus 主键）
     * @throws com.agent.management.common.exception.BusinessException 当 VectorStore 不可用或调用失败
     */
    List<String> add(List<Document> documents);

    /**
     * 按 id 列表删除向量
     */
    void deleteByIds(List<String> ids);

    /**
     * 相似度检索：对查询文本向量化后从 Milvus 召回 TopK 条匹配记录
     *
     * <p>Document 的 metadata 字段包含入库时写入的 documentId / chunkId / chunkIndex /
     * categoryId / docName，调用方可直接读取用于结果展示或后处理。</p>
     *
     * @param query             查询文本
     * @param topK              返回条数上限
     * @param similarityThreshold 相似度阈值（0~1，null 表示使用 VectorStore 默认值 0.0）
     * @param filterExpression  元数据过滤表达式（Spring AI 字符串语法，如 "categoryId == 5"），null/空表示不过滤
     * @return 命中的 Document 列表（按相似度降序）
     * @throws com.agent.management.common.exception.BusinessException 当 VectorStore 不可用或调用失败
     */
    List<Document> similaritySearch(String query, int topK, Double similarityThreshold, String filterExpression);

    /**
     * VectorStore 是否可用（UI 提示用）
     */
    boolean isAvailable();
}
