// ============================================================================
// 【文件说明】IHwSearchSchemaService.cs - 搜索表结构服务接口
// ============================================================================
// 这个接口定义了搜索表结构初始化的契约。
// 
// 【为什么需要接口？】
// 1. 依赖倒置原则（DIP）：高层模块依赖抽象，不依赖具体实现
// 2. 便于测试：可以 Mock 这个接口进行单元测试
// 3. 便于扩展：未来可以有不同的实现（如支持 PostgreSQL）
// 
// 【与 Java Spring Boot 的对比】
// Java Spring Boot:
//   public interface IHwSearchSchemaService {
//       CompletableFuture<Void> ensureCreatedAsync();
//   }
// 
// C# ASP.NET Core:
//   public interface IHwSearchSchemaService {
//       Task EnsureCreatedAsync(CancellationToken cancellationToken = default);
//   }
// 
// 两者概念完全一样，只是异步返回类型不同：
// - Java 用 CompletableFuture
// - C# 用 Task
// ============================================================================

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 搜索表结构服务接口。
/// <para>
/// 【C# 语法知识点 - 接口定义】
/// public interface IHwSearchSchemaService
/// 
/// 接口定义了一组方法签名，不包含实现：
/// - 只声明方法，不实现方法
/// - 实现类必须提供所有方法的具体实现
/// 
/// 对比 Java：
/// Java 的接口语法完全一样：
///   public interface IHwSearchSchemaService {
///       void ensureCreatedAsync();
///   }
/// 
/// 【命名约定】
/// C# 接口命名约定：I + PascalCase
/// - IHwSearchSchemaService：I 前缀表示 Interface
/// - HwSearchSchemaService：实现类不加 I 前缀
/// 
/// Java 接口命名约定：不加 I 前缀
/// - HwSearchSchemaService：接口
/// - HwSearchSchemaServiceImpl：实现类
/// </para>
/// </summary>
public interface IHwSearchSchemaService
{
    /// <summary>
    /// 确保搜索表已创建。
    /// <para>
    /// 【方法语义】
    /// "Ensure" 表示"确保"，是一种幂等操作：
    /// - 如果表已存在，不做任何操作
    /// - 如果表不存在，创建表
    /// 
    /// 对比 "Create"：
    /// - Create：每次都创建，重复调用会报错
    /// - EnsureCreated：幂等，可以安全地多次调用
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - CancellationToken 参数】
    /// CancellationToken cancellationToken = default
    /// 
    /// 这是 C# 异步编程的标准模式：
    /// - CancellationToken：取消令牌，用于取消长时间运行的操作
    /// - = default：默认值，调用时可以不传
    /// 
    /// 使用场景：
    /// 1. 用户取消请求：浏览器关闭或刷新
    /// 2. 超时取消：操作超过指定时间
    /// 3. 应用关闭：服务器需要优雅关闭
    /// 
    /// 对比 Java：
    /// Java 没有内置的取消机制，通常用自定义标志位：
    ///   private volatile boolean cancelled = false;
    ///   public void cancel() { cancelled = true; }
    /// 
    /// C# 的 CancellationToken 是框架级支持，更优雅。
    /// </para>
    /// </summary>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>异步任务</returns>
    Task EnsureCreatedAsync(CancellationToken cancellationToken = default);
}