// =============================================================================
// GB5 Framework — IQueryOrchestrator
// Namespace : FrameworkBLL.ReportOrchestration
// Purpose   : Central entry point for ALL report and analysis execution.
//             Orchestrates: datasource resolution, async decision, URI call
//             (standard reports) or dynamic SQL execution (analysis reports),
//             pivot transformation, export, caching, and SysJob submission.
//
// What callers do:
//   1. Build a ReportExecutionContext (identity + parameters + call type).
//   2. Call IQueryOrchestrator.ExecuteReportAsync(context).
//   3. Inspect ReportExecutionResult.ResultType:
//        SyncCompleted  → stream GridData or ExportStream to browser.
//        AsyncSubmitted → return SysJobId; Angular shows My Reports inbox.
//        Failed         → return error response with CorrelationId.
//
// What callers do NOT do:
//   - Resolve DB connections.
//   - Decide sync vs async.
//   - Call module endpoints directly.
//   - Generate export files.
//   - Submit SysJobs.
//
// Lifetime: Scoped (one instance per HTTP request).
// =============================================================================

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

namespace FrameworkBLL.ReportOrchestration
{
    /// <summary>
    /// Central orchestrator for report and analysis execution.
    /// All module API endpoints and background job workers call this interface;
    /// no module should construct DB connections or resolve datasources directly
    /// for reporting purposes.
    /// </summary>
    public interface IQueryOrchestrator
    {
        // =====================================================================
        // PRIMARY ENTRY POINT
        // =====================================================================

        /// <summary>
        /// Executes a report or analysis as described by
        /// <paramref name="context"/> and returns a unified result.
        /// </summary>
        /// <remarks>
        /// <b>Pipeline stages (in order):</b>
        /// <list type="number">
        ///   <item>Load MREPORTCONFIG / MANALYSISWORKSPACE metadata.</item>
        ///   <item>Validate requested ExportFormat against ALLOWEDEXPORTFORMATS.</item>
        ///   <item>Evaluate datasource rules (Auto → concrete DataSourceType).</item>
        ///   <item>Resolve IDbConnection via IReportConnectionResolver.</item>
        ///   <item>Evaluate async decision (AsyncMode + DateRangeDays + policy).</item>
        ///   <item>
        ///     <b>If sync:</b> execute (URI call or dynamic SQL), optionally pivot,
        ///     export, optionally cache, return SyncCompleted result.
        ///   </item>
        ///   <item>
        ///     <b>If async:</b> submit SysJob with resolved context serialised as
        ///     TSYSJOB.PARAMETERS, return AsyncSubmitted result with SysJobId.
        ///   </item>
        /// </list>
        ///
        /// <b>Performance notes:</b>
        /// <list type="bullet">
        ///   <item>MREPORTCONFIG is cached within the request (Scoped resolver).</item>
        ///   <item>Result data is cached in IDistributedCache when
        ///         MREPORTCONFIG.CACHEDURATIONMINUTES &gt; 0.</item>
        ///   <item>NOLOCK hints are applied automatically when
        ///         MREPORTCONFIG.ISNOLOCKALLOWED = true and provider = SQL Server.</item>
        ///   <item>CancellationToken from context is propagated to all async ops.</item>
        /// </list>
        /// </remarks>
        /// <param name="context">
        /// Fully populated execution context. At minimum must carry LoginDTO,
        /// ReportId or AnalysisId, CallType, Parameters, RequestedFormat,
        /// and CancellationToken.
        /// </param>
        /// <returns>
        /// A <see cref="ReportExecutionResult"/> with ResultType indicating
        /// how the caller should respond to the browser.
        /// Never throws — exceptions are caught and returned as
        /// <see cref="ReportResultType.Failed"/> with a safe error message.
        /// </returns>
        Task<ReportExecutionResult> ExecuteReportAsync(ReportExecutionContext context);

        // =====================================================================
        // ASYNC (SYSJOB WORKER) ENTRY POINT
        // =====================================================================

        /// <summary>
        /// Called by the SysJob worker to execute a previously queued async
        /// report. Deserialises the context from TSYSJOB.PARAMETERS, executes,
        /// generates the export file, saves it, and updates TSYSJOB.RESULTLOCATION.
        /// </summary>
        /// <remarks>
        /// This overload always executes synchronously relative to the caller
        /// (the worker thread). It does not re-submit as another SysJob.
        /// TSYSJOB.RUNSTATUS is managed by the SysJob framework — the worker
        /// sets it to Running before calling this, and to Completed/Failed after.
        /// </remarks>
        /// <param name="sysJobId">
        /// The TSYSJOB.SYSJOBID being executed. Used to load parameters
        /// and update result location on completion.
        /// </param>
        /// <param name="loginDTO">
        /// The session context reconstructed by the SysJob worker from the
        /// TSYSJOB row (ClientId, UserId, ServerConfigId etc.).
        /// </param>
        /// <param name="cancellationToken">
        /// Cancellation token from the worker; triggered on job timeout or
        /// explicit cancellation from the My Reports inbox.
        /// </param>
        /// <returns>
        /// The file path/URL stored in TSYSJOB.RESULTLOCATION on success.
        /// Throws on unrecoverable failure — worker sets RUNSTATUS = Failed.
        /// </returns>
        Task<string> ExecuteAsyncJobAsync(
            int sysJobId,
            LoginDTO loginDTO,
            CancellationToken cancellationToken = default);

        // =====================================================================
        // CONTEXT BUILDER — fluent helper for callers
        // =====================================================================

        /// <summary>
        /// Fluent builder to construct a <see cref="ReportExecutionContext"/>
        /// for a standard report (MMenu REPORTTYPE 1 or 2).
        /// </summary>
        IReportContextBuilder ForStandardReport(
            LoginDTO loginDTO,
            int reportId,
            int viewId = -1);

        /// <summary>
        /// Fluent builder to construct a <see cref="ReportExecutionContext"/>
        /// for an analysis report (MMenu REPORTTYPE 0 or 3).
        /// </summary>
        IReportContextBuilder ForAnalysisReport(
            LoginDTO loginDTO,
            int analysisId,
            int queryId = -1);
    }

    // =========================================================================
    // IReportContextBuilder — fluent builder interface
    // =========================================================================

    /// <summary>
    /// Fluent builder for <see cref="ReportExecutionContext"/>.
    /// Obtained via <see cref="IQueryOrchestrator.ForStandardReport"/> or
    /// <see cref="IQueryOrchestrator.ForAnalysisReport"/>.
    /// </summary>
    public interface IReportContextBuilder
    {
        /// <summary>
        /// Adds filter parameters. Accepts an anonymous object, a dictionary,
        /// or any object serialisable to key-value pairs.
        /// Existing parameters are merged (last-write-wins per key).
        /// </summary>
        IReportContextBuilder WithParameters(object parameters);

        /// <summary>
        /// Sets the requested export format.
        /// Validated against MREPORTCONFIG.ALLOWEDEXPORTFORMATS at execution time.
        /// Default: Grid.
        /// </summary>
        IReportContextBuilder WithFormat(ExportFormat format);

        /// <summary>
        /// Extracts and sets FromDate / ToDate from the parameters dictionary
        /// for DateRangeDays calculation. Call after WithParameters.
        /// Keys default to "FromDate" and "ToDate" — override if your report
        /// uses different parameter names.
        /// </summary>
        IReportContextBuilder WithDateRange(
            string fromDateKey = "FromDate",
            string toDateKey   = "ToDate");

        /// <summary>
        /// Sets the CancellationToken from the HTTP request.
        /// Always call this: <c>.WithCancellation(HttpContext.RequestAborted)</c>
        /// </summary>
        IReportContextBuilder WithCancellation(CancellationToken cancellationToken);

        /// <summary>
        /// Explicitly overrides the DataSourceType, bypassing MREPORTCONFIG
        /// and rule evaluation. Use sparingly — prefer metadata-driven routing.
        /// Intended for admin/debug endpoints only.
        /// </summary>
        IReportContextBuilder WithDataSourceOverride(DataSourceType dataSource);

        /// <summary>Constructs and returns the immutable <see cref="ReportExecutionContext"/>.</summary>
        ReportExecutionContext Build();
    }

    // =========================================================================
    // IReportEndpoint — contract every module report endpoint must satisfy
    // =========================================================================

    /// <summary>
    /// Contract for a module report endpoint. Implemented by module classes
    /// that inherit <c>FrameworkSL.ReportOrchestration.ReportEndpointBase</c>.
    /// The orchestrator calls <see cref="GetReportDataAsync"/> after resolving
    /// the connection and making the async/sync decision.
    /// </summary>
    public interface IReportEndpoint
    {
        /// <summary>
        /// Fetches the flat report data rows for the given request context.
        /// The connection is already open when this method is called.
        /// Do not close or dispose it — the orchestrator manages lifetime.
        /// </summary>
        System.Collections.Generic.IAsyncEnumerable<System.Collections.Generic.IReadOnlyDictionary<string, object?>> GetReportDataAsync(
            ReportExecutionContext context,
            System.Data.IDbConnection connection,
            CancellationToken cancellationToken = default);
    }

    // =========================================================================
    // IReportEndpointRegistry — discovery and lookup of module endpoints
    // =========================================================================

    /// <summary>
    /// Registry of all module report endpoint implementations.
    /// Singleton — populated at startup by scanning module assemblies.
    /// Used by <see cref="IQueryOrchestrator"/> to locate the correct endpoint.
    /// </summary>
    public interface IReportEndpointRegistry
    {
        /// <summary>
        /// Locates the <see cref="IReportEndpoint"/> for the given report code.
        /// Returns null when no endpoint is registered for this code.
        /// </summary>
        IReportEndpoint? Resolve(string reportCode);

        /// <summary>Returns all registered report codes.</summary>
        System.Collections.Generic.IReadOnlyList<string> GetRegisteredReportCodes();
    }

    // =========================================================================
    // IAsyncDecisionEngine — injectable async/sync decision logic
    // =========================================================================

    /// <summary>
    /// Evaluates whether a report request should execute synchronously or be
    /// submitted as a SysJob, based on AsyncMode, DateRangeDays, and policy.
    /// Separated from the orchestrator so policy rules can be swapped/extended
    /// without changing orchestration logic.
    /// Registered as <b>Scoped</b>.
    /// </summary>
    public interface IAsyncDecisionEngine
    {
        /// <summary>
        /// Returns <c>true</c> if the request should be submitted as a SysJob.
        /// </summary>
        /// <remarks>
        /// Decision logic by AsyncMode:
        /// <list type="bullet">
        ///   <item><b>Auto</b>: true when DateRangeDays &gt; AsyncThresholdDays.</item>
        ///   <item><b>AlwaysAsync</b>: always true.</item>
        ///   <item><b>AlwaysSync</b>: always false.</item>
        ///   <item><b>PolicyBased</b>: evaluates MREPORTPOLICY rules for
        ///         ClientId, RoleId, ModuleId, time-of-day. Falls back to
        ///         Auto if no policy matches.</item>
        /// </list>
        /// </remarks>
        /// <param name="context">
        /// Must have ReportConfig set (provides AsyncMode + AsyncThresholdDays).
        /// </param>
        /// <param name="cancellationToken">Cancellation token for async operation.</param>
        Task<bool> ShouldRunAsyncAsync(
            ReportExecutionContext context,
            CancellationToken cancellationToken = default);
    }
}