// =============================================================================
// GB5 Framework — ReportExecutionContext
// Namespace : GB5Shared.DTO.ReportOrchestration
// Purpose   : The single DTO that flows through the entire orchestration
//             pipeline. Carries identity, request parameters, resolved
//             datasource, execution decisions, and result metadata.
//             Created by QueryOrchestrator; read by all downstream layers.
// =============================================================================

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

namespace GB5Shared.DTO.ReportOrchestration
{
    /// <summary>
    /// Central context object for a single report execution request.
    /// Instantiated by <see cref="IQueryOrchestrator"/> and threaded through
    /// connection resolution, execution, pivot, and export stages.
    /// Immutable after construction except for fields set by the orchestrator
    /// during pipeline stages (ResolvedDataSource, IsAsync, JobId, etc.).
    /// </summary>
    public sealed class ReportExecutionContext
    {
        // ---------------------------------------------------------------------
        // IDENTITY — who is requesting, for which report
        // ---------------------------------------------------------------------

        /// <summary>
        /// The authenticated session. Source of ClientId, UserId, RoleId,
        /// ServerConfigId, DatabaseType, WorkDate, PeriodFromDate/ToDate.
        /// Never null; set at construction.
        /// </summary>
        public LoginDTO LoginDTO { get; init; } = null!;

        /// <summary>
        /// The MREPORT.REPORTID being executed.
        /// -1 for analysis reports (use AnalysisId instead).
        /// </summary>
        public int ReportId { get; init; } = -1;

        /// <summary>
        /// The MANALYSIS.ANALYSISID being executed.
        /// -1 for standard reports (use ReportId instead).
        /// </summary>
        public int AnalysisId { get; init; } = -1;

        /// <summary>
        /// The specific MREPORTVIEW.REPORTVIEWID requested.
        /// -1 means use the default view (ISDEFAULTVIEW = 0).
        /// </summary>
        public int ReportViewId { get; init; } = -1;

        /// <summary>
        /// Discriminates the call path so the orchestrator applies the
        /// correct resolution, execution, and export strategy.
        /// </summary>
        public ReportCallType CallType { get; init; } = ReportCallType.StandardReport;

        // ---------------------------------------------------------------------
        // REQUEST PARAMETERS — passed through to the module endpoint
        // ---------------------------------------------------------------------

        /// <summary>
        /// Report-specific filter parameters (date range, dimension filters,
        /// free-text search etc.) as key-value pairs.
        /// Forwarded as-is to the module endpoint via the HTTP request body.
        /// The orchestrator reads FromDate / ToDate for async decisions.
        /// </summary>
        public Dictionary<string, object?> Parameters { get; init; } = new();

        /// <summary>
        /// Requested export format. Validated against
        /// MREPORTCONFIG.ALLOWEDEXPORTFORMATS before execution.
        /// </summary>
        public ExportFormat RequestedFormat { get; init; } = ExportFormat.Grid;

        /// <summary>
        /// Convenience: FromDate extracted from Parameters["FromDate"].
        /// Used for period-based async threshold calculation.
        /// Null when not present or not applicable.
        /// </summary>
        public DateTime? FromDate { get; init; }

        /// <summary>
        /// Convenience: ToDate extracted from Parameters["ToDate"].
        /// Used for period-based async threshold calculation.
        /// Null when not present or not applicable.
        /// </summary>
        public DateTime? ToDate { get; init; }

        /// <summary>
        /// Date range in days between FromDate and ToDate.
        /// Returns 0 when either date is absent.
        /// Used by AsyncMode.Auto threshold evaluation.
        /// </summary>
        public int DateRangeDays =>
            (FromDate.HasValue && ToDate.HasValue)
                ? Math.Max(0, (int)(ToDate.Value.Date - FromDate.Value.Date).TotalDays)
                : 0;

        // ---------------------------------------------------------------------
        // RESOLVED CONFIGURATION — set by orchestrator after loading MREPORTCONFIG
        // ---------------------------------------------------------------------

        /// <summary>
        /// The MREPORTCONFIG loaded for this report.
        /// Null for analysis reports or when config is not yet loaded.
        /// </summary>
        public ReportConfigDTO? ReportConfig { get; set; }

        /// <summary>
        /// The final resolved DataSourceType after applying
        /// MREPORTCONFIG.DATASOURCETYPE and any matching MREPORTDATASOURCERULE.
        /// Set by the orchestrator's source resolution stage.
        /// </summary>
        public DataSourceType ResolvedDataSource { get; set; } = DataSourceType.Oltp;

        /// <summary>
        /// The resolved server configuration for the chosen DataSourceType.
        /// Set by <see cref="IReportConnectionResolver"/>.
        /// Contains the connection string and provider type — never serialised.
        /// </summary>
        public ReportServerConfigDTO? ResolvedServerConfig { get; set; }

        // ---------------------------------------------------------------------
        // EXECUTION DECISIONS — set by orchestrator before execution
        // ---------------------------------------------------------------------

        /// <summary>
        /// True when this request will be executed asynchronously via SysJob.
        /// Determined by AsyncMode + DateRangeDays + policy evaluation.
        /// </summary>
        public bool IsAsync { get; set; }

        /// <summary>
        /// The SysJob SYSJOBID submitted for async execution.
        /// -1 when IsAsync = false or before SysJob submission.
        /// </summary>
        public int SysJobId { get; set; } = -1;

        /// <summary>
        /// Query execution timeout in seconds.
        /// Sourced from MREPORTCONFIG.QUERYTIMEOUTSECONDS.
        /// Sync default: 30s. Async default: 300s.
        /// </summary>
        public int QueryTimeoutSeconds { get; set; } = 30;

        /// <summary>
        /// When true and DataSource is ReportDB or ArchiveDB on SQL Server,
        /// the orchestrator appends NOLOCK hints via query wrapper.
        /// Sourced from MREPORTCONFIG.ISNOLOCKALLOWED.
        /// Always false for OLTP writes and Oracle/PostgreSQL.
        /// </summary>
        public bool ApplyNoLock { get; set; }

        /// <summary>
        /// CancellationToken propagated from the HTTP request through the
        /// full execution pipeline (connection open, query, export).
        /// Allows browser-cancel to abort long-running queries.
        /// </summary>
        public CancellationToken CancellationToken { get; init; } = CancellationToken.None;

        // ---------------------------------------------------------------------
        // TRACING — for diagnostics and audit
        // ---------------------------------------------------------------------

        /// <summary>
        /// Unique identifier for this execution request.
        /// Used to correlate log entries across all pipeline stages.
        /// </summary>
        public Guid CorrelationId { get; init; } = Guid.NewGuid();

        /// <summary>
        /// UTC timestamp when this context was created (request received).
        /// </summary>
        public DateTime RequestedAtUtc { get; init; } = DateTime.UtcNow;
    }

    // =========================================================================
    // ReportConfigDTO — subset of MREPORTCONFIG columns loaded by orchestrator
    // =========================================================================

    /// <summary>
    /// Projection of MREPORTCONFIG loaded by the orchestrator.
    /// Only the fields needed for execution decisions are included.
    /// Full MREPORTCONFIG entity lives in the DAL layer.
    /// </summary>
    public sealed class ReportConfigDTO
    {
        public int ReportConfigId { get; init; }
        public int ReportId { get; init; }

        /// <summary>Configured datasource preference before rule evaluation.</summary>
        public DataSourceType DataSourceType { get; init; } = DataSourceType.Oltp;

        /// <summary>Controls sync vs async execution decision.</summary>
        public AsyncMode AsyncMode { get; init; } = AsyncMode.Auto;

        /// <summary>
        /// When AsyncMode = Auto, requests with DateRangeDays exceeding this
        /// threshold are submitted as SysJob. Default: 90 days.
        /// </summary>
        public int AsyncThresholdDays { get; init; } = 90;

        /// <summary>Sync query timeout in seconds. Default: 30.</summary>
        public int QueryTimeoutSeconds { get; init; } = 30;

        /// <summary>Async (SysJob) query timeout in seconds. Default: 300.</summary>
        public int AsyncQueryTimeoutSeconds { get; init; } = 300;

        /// <summary>
        /// Minutes to cache the result. 0 = no cache.
        /// Cache key includes ReportId + CacheKeyParams + ClientId.
        /// </summary>
        public int CacheDurationMinutes { get; init; }

        /// <summary>
        /// Comma-separated parameter names that form part of the cache key.
        /// Null = all parameters included in cache key.
        /// </summary>
        public string? CacheKeyParams { get; init; }

        /// <summary>Default export format for this report.</summary>
        public ExportFormat DefaultExportFormat { get; init; } = ExportFormat.Grid;

        /// <summary>
        /// Comma-separated ExportFormat byte values that are allowed.
        /// e.g. "0,1,2" = Grid, PDF, Excel only.
        /// </summary>
        public string AllowedExportFormats { get; init; } = "0,1,2,3";

        /// <summary>Where pivot transformation occurs.</summary>
        public PivotEngine PivotEngine { get; init; } = PivotEngine.None;

        /// <summary>Semantic category for UI grouping and default suggestions.</summary>
        public ReportCategory ReportCategory { get; init; } = ReportCategory.Operational;

        /// <summary>
        /// Whether NOLOCK hints may be applied when routing to ReportDB/ArchiveDB.
        /// Only honoured on SQL Server. False for Oracle/PostgreSQL.
        /// </summary>
        public bool IsNoLockAllowed { get; init; }

        /// <summary>SysJob result file TTL in hours. Default: 24.</summary>
        public int ResultExpiryHours { get; init; } = 24;

        /// <summary>SysJob priority (1–10). Higher = executed first.</summary>
        public byte DefaultPriority { get; init; } = 5;

        /// <summary>
        /// Optional COUNT query used by RuleType=1 (EstimatedRows) to decide
        /// whether to route to ReportDB or ArchiveDB. Null means no estimation query configured.
        /// </summary>
        public string? EstimationQuery { get; init; }
    }
}