// ============================================================================
// 【文件说明】Startup.cs - 门户插件启动类
// ============================================================================
// 这是 Admin.NET 插件架构的核心启动类，负责注册门户模块的所有服务。
//
// 【架构定位 - 什么是插件启动类？】
// 在 Admin.NET/Furion 框架中，插件是一个独立的 .dll 文件，可以被主应用动态加载。
// 每个插件都需要一个 Startup 类来告诉框架：
// 1. 我（插件）提供了哪些服务
// 2. 我需要哪些配置
// 3. 我的中间件应该在什么位置插入
//
// 【对比 Java Spring Boot】
// Java Spring Boot 的自动配置：
//   @Configuration
//   @EnableAutoConfiguration
//   public class MyConfig { ... }
//
// 或者使用 spring.factories 文件声明自动配置类。
//
// Admin.NET 的方式：
//   [AppStartup(100)]
//   public class Startup : AppStartup { ... }
//
// 两者概念相同：都是在应用启动时执行配置代码。
// ============================================================================

using Admin.NET.Core;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;

namespace Admin.NET.Plugin.HwPortal;

/// <summary>
/// 门户插件启动类。
/// <para>
/// 【C# 语法知识点 - AppStartup 特性】
/// [AppStartup(100)] 是 Furion 框架的特性，标记这是一个插件启动类。
/// 
/// 参数 100 是"启动顺序"：
/// - 数值越小，越早执行
/// - 主应用通常是 0-99，插件可以是 100+
/// - 这样可以控制依赖关系：先启动核心服务，再启动插件服务
/// 
/// 对比 Java Spring Boot：
//  Spring 用 @Order 注解或 Ordered 接口控制顺序：
//    @Order(100)
//    public class MyConfig { ... }
/// </para>
/// <para>
/// 【C# 语法知识点 - 继承 AppStartup】
/// public class Startup : AppStartup
/// 
/// AppStartup 是 Furion 提供的基类/接口，定义了插件必须实现的方法：
/// - ConfigureServices：注册服务到 DI 容器
/// - Configure：配置中间件管道
/// 
/// 这是"模板方法模式"的应用：框架定义流程，插件填充具体实现。
/// </para>
/// </summary>
[AppStartup(100)]
public class Startup : AppStartup
{
    /// <summary>
    /// 配置服务（注册到 DI 容器）。
    /// <para>
    /// 【C# 语法知识点 - IServiceCollection】
    /// IServiceCollection 是 ASP.NET Core 的"服务注册表"（依赖注入容器）。
    /// 
    /// 你可以把它想象成一个"服务工厂"：
    /// - 在这里注册服务："如果有人需要 IXxxService，就给他 XxxService 实例"
    /// - 框架会在运行时自动解析依赖关系
    /// 
    /// 对比 Java Spring Boot：
    /// Java 用 @Bean 注解或 @ComponentScan 自动扫描：
    ///   @Configuration
    ///   public class Config {
    ///       @Bean
    ///       public MyService myService() {
    ///           return new MyService();
    ///       }
    ///   }
    /// 
    /// C# 是显式注册（更可控），Java 是自动扫描（更便利），各有优劣。
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 三种服务生命周期】
    /// ASP.NET Core DI 容器支持三种服务生命周期：
    /// 
    /// 1. AddSingleton（单例）：
    ///    - 整个应用只创建一个实例
    ///    - 适合：配置类、工具类、缓存
    ///    - 线程安全需要考虑
    ///    - 类比 Java 的 @Scope("singleton")
    /// 
    /// 2. AddScoped（作用域）：
    ///    - 每个 HTTP 请求创建一个实例
    ///    - 适合：数据库上下文、业务服务
    ///    - 同一个请求内，多次获取返回同一实例
    ///    - 类比 Java 的 @Scope("request")
    /// 
    /// 3. AddTransient（瞬态）：
    ///    - 每次获取都创建新实例
    ///    - 适合：轻量级服务、无状态服务
    ///    - 类比 Java 的 @Scope("prototype")
    /// </para>
    /// </summary>
    /// <param name="services">服务注册表</param>
    public void ConfigureServices(IServiceCollection services)
    {
        // 【配置选项注册】
        // AddConfigurableOptions<T>() 是 Furion 的扩展方法，
        // 把配置类注册到 DI 容器，并绑定到配置文件（如 appsettings.json）。
        // 
        // 对比 Java：
        // Java Spring Boot 用 @ConfigurationProperties + @EnableConfigurationProperties：
        //   @ConfigurationProperties(prefix = "hwportal.search")
        //   public class HwPortalSearchOptions { ... }
        services.AddConfigurableOptions<HwPortalSearchOptions>();

        // 【Singleton 生命周期】
        // 整个应用只保留一个 HwPortalMapperRegistry 实例。
        // 
        // 为什么用 Singleton？
        // 1. HwPortalMapperRegistry 内部缓存了 XML Mapper 定义
        // 2. 这些 XML 在应用运行期间不会变化
        // 3. 多个请求共享同一个缓存，节省内存
        // 
        // 对比 Java：
        // Java 单例通常用 @Service（默认就是单例）
        services.AddSingleton<HwPortalMapperRegistry>();

        // 【Scoped 生命周期】
        // 每个 HTTP 请求创建一个 HwPortalMyBatisExecutor 实例。
        // 
        // 为什么用 Scoped？
        // 1. 执行器依赖数据库客户端（ISqlSugarClient），通常是 Scoped
        // 2. 同一个请求内多次执行 SQL，应该共用同一个连接/事务
        // 3. 请求结束后自动释放资源
        // 
        // 对比 Java：
        // Java 通常用 @Repository 或 @Service（默认单例，但 @Autowired 注入的 SqlSession 是 request-scoped）
        services.AddScoped<HwPortalMyBatisExecutor>();

        // 搜索文本提取器是无状态对象，也注册为 Scoped。
        services.AddScoped<PortalSearchDocConverter>();

        // 【EF Core 数据库上下文注册】
        // AddDbContext<T>() 注册 Entity Framework Core 的数据库上下文。
        // 
        // 为什么用 Lambda 表达式？
        // 参数是一个委托（函数），在第一次需要 DbContext 时才执行配置。
        // 这叫"延迟初始化"，避免应用启动时就建立数据库连接。
        // 
        // 对比 Java：
        // Java Spring Boot 自动配置 DataSource，不需要显式注册：
        //   spring.datasource.url=jdbc:mysql://...
        services.AddDbContext<HwPortalSearchDbContext>((provider, options) =>
        {
            // 从 DI 容器获取配置选项
            // GetRequiredService<T>()：获取服务，如果不存在会抛异常
            // IOptions<T> 是 ASP.NET Core 的配置包装接口
            HwPortalSearchOptions searchOptions = provider.GetRequiredService<IOptions<HwPortalSearchOptions>>().Value;
            DbConnectionOptions dbOptions = provider.GetRequiredService<IOptions<DbConnectionOptions>>().Value;
            
            // 解析连接字符串（可能是独立配置，也可能是复用主库）
            string connectionString = ResolveSearchConnectionString(searchOptions, dbOptions);

            // 配置 MySQL 连接
            // UseMySql()：指定使用 MySQL 数据库提供程序
            // ServerVersion.AutoDetect()：自动检测 MySQL 服务器版本
            options.UseMySql(connectionString, ServerVersion.AutoDetect(connectionString), builder =>
            {
                // 启用失败重试：短暂网络故障时自动重试
                builder.EnableRetryOnFailure();
            });
        });

        // 【注册搜索相关服务】
        // AddScoped<IInterface, TImplementation>() 是接口到实现的映射。
        // 
        // 为什么面向接口编程？
        // 1. 解耦：调用者依赖接口，不依赖具体实现
        // 2. 可测试：单元测试时可以 Mock 接口
        // 3. 可替换：可以随时替换实现类
        // 
        // 对比 Java：
        // Java Spring 自动根据类型注入，通常不需要显式注册：
        //   @Service
        //   public class HwSearchSchemaService implements IHwSearchSchemaService { ... }
        services.AddScoped<IHwSearchSchemaService, HwSearchSchemaService>();
        services.AddScoped<IHwSearchIndexService, HwSearchIndexService>();
        services.AddScoped<HwSearchQueryService>();
        services.AddScoped<LegacyHwSearchQueryService>();
        services.AddScoped<IHwSearchRebuildService, HwSearchRebuildService>();
    }

    /// <summary>
    /// 配置中间件管道。
    /// <para>
    /// 【C# 语法知识点 - IApplicationBuilder】
    /// IApplicationBuilder 是 ASP.NET Core 的"中间件管道构建器"。
    /// 
    /// 什么是中间件？
    /// 中间件是处理 HTTP 请求的"管道组件"，每个中间件可以选择：
    /// 1. 处理请求并返回响应（短路）
    /// 2. 处理请求后，传递给下一个中间件
    /// 3. 请求返回后，执行一些后置处理
    /// 
    /// 中间件执行顺序（洋葱模型）：
    /// 请求 → 中间件1 → 中间件2 → 控制器 → 中间件2 → 中间件1 → 响应
    /// 
    /// 对比 Java：
    /// Java Spring Boot 用 Filter 或 HandlerInterceptor：
    ///   @Component
    ///   public class MyFilter implements Filter { ... }
    /// </para>
    /// <para>
    /// 【当前实现说明】
    /// 这个方法目前为空，因为门户插件不需要额外的中间件。
    /// 如果未来需要添加自定义中间件（如请求日志、权限校验），在这里添加。
    /// </para>
    /// </summary>
    /// <param name="app">应用构建器</param>
    /// <param name="env">主机环境信息</param>
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        // 这里暂时不追加自定义中间件。
        // 如果未来 hw-portal 需要自己的中间件，也是在这里接入。
        //
        // 示例：添加一个自定义中间件
        // app.UseMiddleware<HwPortalMiddleware>();
        //
        // 示例：添加静态文件服务
        // app.UseStaticFiles();
    }

    /// <summary>
    /// 解析搜索数据库的连接字符串。
    /// <para>
    /// 【业务逻辑说明】
    /// 搜索功能可以：
    /// 1. 使用独立的 MySQL 连接（推荐，隔离搜索负载）
    /// 2. 复用主库连接（简单，但不适合高并发搜索场景）
    /// 
    /// 这个方法实现"自动回退"逻辑：
    /// - 如果配置了独立连接，就用独立连接
    /// - 如果没配置且允许回退，就复用主库
    /// - 如果没配置且不允许回退，抛异常
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - private static 方法】
    /// private：只能在当前类内部调用
    /// static：不依赖实例状态，可以直接用 Startup.ResolveSearchConnectionString(...) 调用
    /// 
    /// 为什么用 static？
    /// 1. 这个方法不访问任何实例成员（没有用到 this）
    /// 2. 标记为 static 可以让编译器优化
    /// 3. 语义清晰：这是一个纯工具方法
    /// </para>
    /// <para>
    /// 【C# 语法知识点 - 空值检查】
    /// string.IsNullOrWhiteSpace(str) 检查：
    /// - null
    /// - 空字符串 ""
    /// - 纯空白字符串 "   "
    /// 
    /// 这是 .NET 提供的最佳实践，比 str == null || str.Trim() == "" 更高效。
    /// 
    /// 对比 Java：
    /// Java 需要：
    ///   if (str == null || str.trim().isEmpty()) { ... }
    /// </para>
    /// </summary>
    /// <param name="searchOptions">搜索配置选项</param>
    /// <param name="dbOptions">数据库连接配置</param>
    /// <returns>解析后的连接字符串</returns>
    /// <exception cref="InvalidOperationException">配置无效时抛出</exception>
    private static string ResolveSearchConnectionString(HwPortalSearchOptions searchOptions, DbConnectionOptions dbOptions)
    {
        // 【第一优先级】如果配置了独立的搜索连接串，直接使用
        if (!string.IsNullOrWhiteSpace(searchOptions.ConnectionString))
        {
            // .Trim() 去除首尾空格，避免配置错误
            return searchOptions.ConnectionString.Trim();
        }

        // 【检查回退策略】
        // 如果不允许回退到主库连接，直接抛异常
        // 这是"防御性编程"：明确失败比隐式行为更安全
        if (!searchOptions.UseMainDbConnectionWhenEmpty)
        {
            throw new InvalidOperationException("HwPortalSearch.ConnectionString 未配置，且已关闭主库回退。");
        }

        // 【第二优先级】复用主库连接
        // FirstOrDefault() 是 LINQ 方法，返回第一个元素或默认值（null）
        // 
        // 对比 Java：
        // Java Stream：dbOptions.getConnectionConfigs().stream().findFirst().orElse(null);
        DbConnectionConfig mainConfig = dbOptions?.ConnectionConfigs?.FirstOrDefault();
        
        // 检查主库连接是否存在且有效
        if (mainConfig == null || string.IsNullOrWhiteSpace(mainConfig.ConnectionString))
        {
            throw new InvalidOperationException("未找到可复用的主库连接串，请在 Search.json 中配置 HwPortalSearch.ConnectionString。");
        }

        // 【数据库类型检查】
        // 当前搜索功能只支持 MySQL，如果主库是 SQL Server/PostgreSQL 等，不能复用
        // 这是业务约束，提前检查可以避免运行时的奇怪错误
        if (mainConfig.DbType != SqlSugar.DbType.MySql && mainConfig.DbType != SqlSugar.DbType.MySqlConnector)
        {
            throw new InvalidOperationException("HwPortalSearch 默认只支持复用 MySQL 主库连接，请单独配置 HwPortalSearch.ConnectionString。");
        }

        // 【获取连接字符串】
        string connectionString = mainConfig.ConnectionString;
        
        // 【加密处理】
        // 如果主库连接串是加密的（生产环境推荐），需要解密
        // DbSettings?.EnableConnStringEncrypt 是"可空链式调用"：
        // - 如果 DbSettings 为 null，不会抛异常，整个表达式为 null
        // - 这是 C# 的"空条件运算符"?. 语法
        //
        // 对比 Java：
        // Java 需要：
        //   if (mainConfig.getDbSettings() != null && mainConfig.getDbSettings().getEnableConnStringEncrypt()) { ... }
        if (mainConfig.DbSettings?.EnableConnStringEncrypt == true)
        {
            // 调用框架提供的解密工具
            connectionString = CryptogramUtil.Decrypt(connectionString);
        }

        return connectionString;
    }
}