// =============================================================================
// GB5 Framework — IReportConnectionResolver
// Namespace : FrameworkBLL.ReportOrchestration
// Purpose   : Resolves the correct IDbConnection for a given DataSourceType,
//             derived entirely from the LoginDTO session (which carries
//             ServerConfigId → MSERVERCONFIG). No runtime DB lookup required.
//
// Resolution logic:
//   DataSourceType.Oltp      → LoginDTO.ServerConfigId
//   DataSourceType.ReportDb  → MSERVERCONFIG.REPORTSERVERCONFIGID  (-1 = OLTP fallback)
//   DataSourceType.ArchiveDb → MSERVERCONFIG.ARCHIVESERVERCONFIGID (-1 = OLTP fallback)
//   DataSourceType.Auto      → caller must resolve via IDataSourceRuleEvaluator first
//
// Provider:
//   LoginDTO.DatabaseType    → DatabaseProviderType enum
//   0 = SqlServer  (Microsoft.Data.SqlClient)
//   1 = Oracle     (Oracle.ManagedDataAccess)
//   2 = PostgreSQL (Npgsql)
//   3 = MySQL      (MySql.Data)
//
// Lifetime: Scoped (one instance per HTTP request; caches resolved configs
//           within the request to avoid repeated MSERVERCONFIG lookups).
// =============================================================================

using System.Data;
using GB5Shared.DTO.Framework.Login;
using GB5Shared.DTO.ReportOrchestration;
using GB5Shared.Enums.ReportOrchestration;

namespace FrameworkBLL.ReportOrchestration
{
    /// <summary>
    /// Resolves a ready-to-open <see cref="IDbConnection"/> for the requested
    /// <see cref="DataSourceType"/>, using the session context in
    /// <see cref="LoginDTO"/> and the pre-loaded <see cref="ServerConfigCache"/>.
    /// </summary>
    /// <remarks>
    /// Implementations must:
    /// <list type="bullet">
    ///   <item>Be registered as <b>Scoped</b> in DI.</item>
    ///   <item>Cache resolved <see cref="ReportServerConfigDTO"/> instances
    ///         within the request (avoid repeated lookups per pipeline stage).</item>
    ///   <item>Return connections in a <b>closed</b> state; the caller opens
    ///         them so that Dapper / ADO.NET lifetime is controlled explicitly.</item>
    ///   <item>Never log or expose connection strings.</item>
    /// </list>
    /// </remarks>
    public interface IReportConnectionResolver
    {
        /// <summary>
        /// Resolves a closed <see cref="IDbConnection"/> for the given
        /// <paramref name="dataSource"/> using the session in
        /// <paramref name="loginDTO"/>.
        /// </summary>
        /// <param name="loginDTO">
        /// The authenticated session. Must carry a valid
        /// <see cref="LoginDTO.ServerConfigId"/>.
        /// </param>
        /// <param name="dataSource">
        /// The logical data source. Must not be
        /// <see cref="DataSourceType.Auto"/> — resolve Auto to a concrete
        /// source via <see cref="IDataSourceRuleEvaluator"/> before calling.
        /// </param>
        /// <param name="cancellationToken">Propagated from the HTTP request.</param>
        /// <returns>
        /// A closed <see cref="IDbConnection"/> of the correct provider type.
        /// Caller is responsible for opening and disposing.
        /// </returns>
        /// <exception cref="ArgumentException">
        /// Thrown when <paramref name="dataSource"/> is
        /// <see cref="DataSourceType.Auto"/>.
        /// </exception>
        /// <exception cref="InvalidOperationException">
        /// Thrown when the MSERVERCONFIG row cannot be located or the
        /// connection string cannot be formed.
        /// </exception>
        Task<IDbConnection> ResolveConnectionAsync(
            LoginDTO loginDTO,
            DataSourceType dataSource,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Returns the resolved <see cref="ReportServerConfigDTO"/> for the
        /// given <paramref name="dataSource"/> without opening a connection.
        /// Use this when you need metadata (ProviderType, IsDedicatedAnalyticsDb)
        /// to make decisions (e.g. whether to apply NOLOCK hints) before
        /// opening a connection.
        /// </summary>
        /// <param name="loginDTO">The authenticated session.</param>
        /// <param name="dataSource">
        /// The logical data source. Must not be <see cref="DataSourceType.Auto"/>.
        /// </param>
        /// <param name="cancellationToken">Propagated from the HTTP request.</param>
        Task<ReportServerConfigDTO> ResolveConfigAsync(
            LoginDTO loginDTO,
            DataSourceType dataSource,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Checks whether a dedicated analytics database is configured for
        /// <paramref name="dataSource"/>. Returns <c>false</c> when the
        /// config falls back to OLTP (REPORTSERVERCONFIGID /
        /// ARCHIVESERVERCONFIGID = -1), meaning the report will execute
        /// against OLTP — callers should log a warning in this case.
        /// </summary>
        /// <param name="loginDTO">The authenticated session.</param>
        /// <param name="dataSource">
        /// ReportDb or ArchiveDb. Returns false for Oltp (trivially true).
        /// </param>
        bool IsDedicatedDbConfigured(LoginDTO loginDTO, DataSourceType dataSource);
    }

    // =========================================================================
    // IDataSourceRuleEvaluator
    // Resolves DataSourceType.Auto → concrete source using MREPORTDATASOURCERULE
    // =========================================================================

    /// <summary>
    /// Evaluates <see cref="DataSourceType.Auto"/> reports by applying the
    /// MREPORTDATASOURCERULE rows (ordered by RULEPRIORITY ascending) for the
    /// given report against the current request context.
    /// Returns the first matching rule's TARGETDATASOURCE, or the configured
    /// default from <see cref="ReportConfigDTO.DataSourceType"/> if no rule matches.
    /// </summary>
    /// <remarks>
    /// Rules are loaded once per request and cached within the evaluator.
    /// Rule types supported:
    /// <list type="bullet">
    ///   <item><b>0 — DateRangeDays</b>: matches when
    ///   <see cref="ReportExecutionContext.DateRangeDays"/> &gt;
    ///   MREPORTDATASOURCERULE.THRESHOLDVALUE.</item>
    ///   <item><b>2 — TimeOfDay</b>: matches when the current server hour
    ///   (UTC) is ≥ THRESHOLDVALUE (e.g. route off-hours batches to Archive).</item>
    ///   <item><b>3 — Manual</b>: never matched automatically; only via
    ///   <see cref="AsyncMode.AlwaysAsync"/>.</item>
    /// </list>
    /// Registered as <b>Scoped</b>.
    /// </remarks>
    public interface IDataSourceRuleEvaluator
    {
        /// <summary>
        /// Resolves the concrete <see cref="DataSourceType"/> for the given
        /// execution context. Safe to call even when the config's
        /// DataSourceType is already concrete (returns it unchanged).
        /// </summary>
        /// <param name="context">
        /// The partially-initialised execution context. Must have
        /// <see cref="ReportExecutionContext.ReportConfig"/> set.
        /// </param>
        /// <param name="cancellationToken">Propagated from the HTTP request.</param>
        /// <returns>
        /// A concrete <see cref="DataSourceType"/> — never
        /// <see cref="DataSourceType.Auto"/>.
        /// </returns>
        Task<DataSourceType> EvaluateAsync(
            ReportExecutionContext context,
            CancellationToken cancellationToken = default);
    }

    // =========================================================================
    // ServerConfigCache — typed cache populated at login / first access
    // =========================================================================

    /// <summary>
    /// In-memory cache of MSERVERCONFIG rows for the current session.
    /// Keyed by SERVERCONFIGID. Populated lazily on first resolver call.
    /// Avoids repeated DB roundtrips when the same datasource is resolved
    /// across multiple pipeline stages within one HTTP request.
    /// </summary>
    /// <remarks>
    /// Registered as <b>Scoped</b>. Populated by
    /// <see cref="IReportConnectionResolver"/> on first access.
    /// Exposes only the fields required for connection resolution and
    /// NOLOCK/timeout decisions — not the full MSERVERCONFIG entity.
    /// </remarks>
    public interface IServerConfigCache
    {
        /// <summary>
        /// Returns the cached <see cref="CachedServerConfig"/> for the given
        /// <paramref name="serverConfigId"/>, loading from DB if not yet cached.
        /// </summary>
        Task<CachedServerConfig> GetAsync(
            int serverConfigId,
            CancellationToken cancellationToken = default);
    }

    /// <summary>
    /// Projection of MSERVERCONFIG fields required by the resolver.
    /// </summary>
    public sealed class CachedServerConfig
    {
        public int ServerConfigId { get; init; }

        /// <summary>MSERVERCONFIG.DATABASETYPE — maps to DatabaseProviderType.</summary>
        public DatabaseProviderType ProviderType { get; init; }

        public string DatabaseName { get; init; } = string.Empty;
        public string DatabaseUserName { get; init; } = string.Empty;

        /// <summary>
        /// Decrypted at load time; held in memory only.
        /// Never logged, never serialised.
        /// </summary>
        public string DatabasePassword { get; init; } = string.Empty;

        public string DatabasePort { get; init; } = string.Empty;
        public string ServerIp { get; init; } = string.Empty;
        public string ServerMachineName { get; init; } = string.Empty;

        /// <summary>MSERVERCONFIG.REPORTSERVERCONFIGID (-1 = no dedicated ReportDB).</summary>
        public int ReportServerConfigId { get; init; } = -1;

        /// <summary>MSERVERCONFIG.ARCHIVESERVERCONFIGID (-1 = no dedicated ArchiveDB).</summary>
        public int ArchiveServerConfigId { get; init; } = -1;

        /// <summary>MSERVERCONFIG.NATURE (0 Online, 1 Offline, 2 ReferAll).</summary>
        public byte Nature { get; init; }
    }
}