/*
 *  Copyright (c) 2023-2026, Easy-Agents (fuhai999@gmail.com).
 *  <p>
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *  <p>
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  <p>
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.easyagents.search.engine.service;

import com.easyagents.core.document.Document;

import java.util.Collection;
import java.util.List;

/**
 * 关键词搜索引擎统一接口。
 */
public interface DocumentSearcher {

    /**
     * 写入单个文档。
     *
     * @param document 待写入文档
     * @return 写入成功时返回 {@code true}
     */
    boolean addDocument(Document document);

    /**
     * 批量写入文档。
     *
     * <p>默认实现保持现有搜索引擎兼容性；支持原生批量写入的实现应覆盖该方法。</p>
     *
     * @param documents 待写入文档
     * @return 全部文档写入成功时返回 {@code true}
     */
    default boolean addDocuments(List<Document> documents) {
        if (documents == null || documents.isEmpty()) {
            return false;
        }
        for (Document document : documents) {
            if (!addDocument(document)) {
                return false;
            }
        }
        return true;
    }

    /**
     * 删除指定文档。
     *
     * @param id 文档 ID
     * @return 删除成功时返回 {@code true}
     */
    boolean deleteDocument(Object id);

    /**
     * 批量删除指定文档。
     *
     * <p>默认实现保持现有搜索引擎兼容性，并确保所有文档都会尝试删除；
     * 支持原生批量删除的实现应覆盖该方法。</p>
     *
     * @param ids 文档 ID 集合
     * @return 全部文档删除成功时返回 {@code true}
     */
    default boolean deleteDocuments(Collection<?> ids) {
        if (ids == null || ids.isEmpty()) {
            return false;
        }
        boolean success = true;
        for (Object id : ids) {
            if (!deleteDocument(id)) {
                success = false;
            }
        }
        return success;
    }

    /**
     * 更新指定文档。
     *
     * @param document 待更新文档
     * @return 更新成功时返回 {@code true}
     */
    boolean updateDocument(Document document);

    /**
     * 使用默认返回数量搜索文档。
     *
     * @param keyword 搜索关键词
     * @return 命中文档
     */
    default List<Document> searchDocuments(String keyword) {
        return searchDocuments(KeywordSearchRequest.of(keyword, 10));
    }

    /**
     * 搜索指定数量的文档。
     *
     * @param keyword 搜索关键词
     * @param count 最大返回数量
     * @return 命中文档
     */
    default List<Document> searchDocuments(String keyword, int count) {
        return searchDocuments(KeywordSearchRequest.of(keyword, count));
    }

    /**
     * 按请求条件搜索文档。
     *
     * @param request 搜索请求
     * @return 命中文档
     */
    List<Document> searchDocuments(KeywordSearchRequest request);
}
