// ============================================================================
// 【文件说明】IHwSearchIndexService.cs - 搜索索引服务接口
// ============================================================================
// 这个接口定义了搜索索引的增删改操作契约。
// 
// 【CQRS 模式说明】
// 这个接口体现了 CQRS（命令查询职责分离）的"命令"部分：
// - 命令：增删改操作
// - 查询：搜索操作（在 HwSearchQueryService 中）
// 
// 【Upsert 操作说明】
// Upsert = Update + Insert，是一种"合并"操作：
// - 如果记录存在，更新
// - 如果记录不存在，插入
// 
// 这是索引同步的常用模式，避免先查询再决定 insert/update。
// 
// 【与 Java Spring Boot 的对比】
// Java 通常用 Repository 模式：
//   public interface SearchIndexRepository {
//       void upsertMenu(HwWebMenu menu);
//       void deleteMenu(Long menuId);
//   }
// 
// C# 这里用 Service 接口，语义更接近业务操作。
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 搜索索引服务接口。
/// <para>
/// 【服务职责】
/// 负责搜索索引的增删改操作：
/// 1. Upsert：插入或更新索引
/// 2. Delete：删除索引
/// 
/// 注意：这个接口只负责"写"操作，"读"操作在 HwSearchQueryService 中。
/// </para>
/// <para>
/// 【接口方法命名约定】
/// - UpsertXxxAsync：插入或更新某个类型的索引
/// - DeleteXxxAsync：删除某个类型的索引
/// - Async 后缀：表示异步方法
/// 
/// 对比 Java：
/// Java 通常不用 Async 后缀，而是返回 CompletableFuture：
///   CompletableFuture<Void> upsertMenu(HwWebMenu menu);
/// </para>
/// </summary>
public interface IHwSearchIndexService
{
    /// <summary>
    /// 插入或更新菜单索引。
    /// </summary>
    /// <param name="menu">菜单实体</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task UpsertMenuAsync(HwWebMenu menu, CancellationToken cancellationToken = default);

    /// <summary>
    /// 插入或更新页面索引。
    /// </summary>
    /// <param name="web">页面实体</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task UpsertWebAsync(HwWeb web, CancellationToken cancellationToken = default);

    /// <summary>
    /// 插入或更新页面1索引。
    /// </summary>
    /// <param name="web1">页面1实体</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task UpsertWeb1Async(HwWeb1 web1, CancellationToken cancellationToken = default);

    /// <summary>
    /// 插入或更新文档索引。
    /// </summary>
    /// <param name="document">文档实体</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task UpsertDocumentAsync(HwWebDocument document, CancellationToken cancellationToken = default);

    /// <summary>
    /// 插入或更新配置类型索引。
    /// </summary>
    /// <param name="configType">配置类型实体</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task UpsertConfigTypeAsync(HwPortalConfigType configType, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除菜单索引。
    /// </summary>
    /// <param name="menuId">菜单ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task DeleteMenuAsync(long menuId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除页面索引。
    /// </summary>
    /// <param name="webCode">页面编码</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task DeleteWebAsync(long webCode, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除页面1索引。
    /// <para>
    /// 【复合主键删除】
    /// Web1 的索引由多个字段组成复合键：
    /// - webCode：页面编码
    /// - typeId：类型ID
    /// - deviceId：设备ID
    /// 
    /// 删除时需要提供所有键字段。
    /// </para>
    /// </summary>
    /// <param name="webCode">页面编码</param>
    /// <param name="typeId">类型ID</param>
    /// <param name="deviceId">设备ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task DeleteWeb1Async(long webCode, long typeId, long deviceId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除文档索引。
    /// </summary>
    /// <param name="documentId">文档ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task DeleteDocumentAsync(string documentId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除配置类型索引。
    /// </summary>
    /// <param name="configTypeId">配置类型ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task DeleteConfigTypeAsync(long configTypeId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据文档ID删除索引。
    /// <para>
    /// 【通用删除方法】
    /// DocId 是索引的全局唯一标识，格式：{SourceType}_{BizId}
    /// 
    /// 这个方法提供了更通用的删除方式：
    /// - 不需要知道具体类型
    /// - 只需要 DocId
    /// 
    /// 使用场景：
    /// 1. 批量删除：遍历 DocId 列表逐个删除
    /// 2. 清理无效索引：根据外部数据源清理
    /// </para>
    /// </summary>
    /// <param name="docId">文档唯一ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task DeleteByDocIdAsync(string docId, CancellationToken cancellationToken = default);
}