// ============================================================================
// 【文件说明】IHwSearchRebuildService.cs - 搜索索引重建服务接口
// ============================================================================
// 这个接口定义了搜索索引重建的契约。
// 
// 【什么是索引重建？】
// 索引重建是指：
// 1. 从业务表读取数据
// 2. 转换成搜索文档格式
// 3. 写入搜索索引表
// 
// 【为什么需要索引重建？】
// 1. 初始化：新环境部署时，索引表是空的
// 2. 修复：索引和业务数据不一致时，重建可以修复
// 3. 升级：索引结构变化时，需要重建所有索引
// 
// 【与 Java Spring Boot 的对比】
// Java 通常用定时任务或消息队列触发重建：
//   @Scheduled(cron = "0 0 2 * * ?")  // 每天凌晨2点
//   public void rebuildIndex() { ... }
// 
// C# 这里通过服务接口，可以在需要时手动触发。
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 搜索索引重建服务接口。
/// <para>
/// 【服务职责】
/// 提供搜索索引的全量重建能力：
/// - 从业务表读取所有数据
/// - 转换成搜索文档格式
/// - 批量写入索引表
/// </para>
/// <para>
/// 【设计模式 - 策略模式】
/// 这个接口支持多种实现：
/// - HwSearchRebuildService：真正的重建服务（在 SearchEf 中）
/// - HwNoopSearchRebuildService：空实现，用于禁用重建功能
/// 
/// 通过接口注入，调用方不需要知道具体实现。
/// </para>
/// </summary>
public interface IHwSearchRebuildService
{
    /// <summary>
    /// 重建所有搜索索引。
    /// <para>
    /// 【重建流程】
    /// 1. 清空现有索引（或标记为删除）
    /// 2. 遍历所有业务表
    /// 3. 读取数据并转换
    /// 4. 批量写入索引表
    /// 
    /// 【注意事项】
    /// - 重建是耗时操作，可能需要几分钟到几小时
    /// - 建议在低峰期执行
    /// - 大表重建可能需要分批处理
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - Task 返回类型】
    /// Task RebuildAllAsync() 返回 Task，表示：
    /// - 这是一个异步方法
    /// - 不返回具体值（类似 Java 的 void）
    /// - 调用方可以 await 等待完成
    /// 
    /// 对比 Java：
    /// Java 返回 CompletableFuture&lt;Void&gt;：
    ///   CompletableFuture<Void> rebuildAllAsync();
    /// </para>
    /// </summary>
    /// <returns>异步任务</returns>
    Task RebuildAllAsync();
}