using GB5Shared.DTO.Framework.Login;
using GB5Shared.QueryExecutor;
using IceImportDAL.DTO.IceImportRun;

namespace IceImportBLL.IceImportRun;

// Run-tracking BLL for ICEIMPORT.TICEIMPORTRUN/TICEIMPORTRUNLOG/TICEIMPORTRUNARTIFACT/
// TICEIMPORTRUNROWRESULT — mirrors AutomationBLL.Run.IRunBLL's shape (EnqueueRun*, AppendLog,
// CompleteRun, SaveArtifact, GetHistory, GetDetail) plus GetRowErrors, which Automation has no
// equivalent of (row-level drill-down is new to this module).
//
// This interface is purely run bookkeeping — it knows nothing about IIceImportPipeline or how a run
// is actually executed. IceImportRunExecutionService (also in this BLL) is the orchestrator that
// calls both this interface and the pipeline together.
public interface IIceImportRunBLL
{
    // Inserts a new TICEIMPORTRUN row (Status=Queued) and, if sourceFileStorageKey is supplied,
    // immediately records + links a "SourceFile" artifact (needed later by RetryImportRun even if
    // the run never progresses past Queued). Returns the new RunId.
    Task<long> EnqueueRunAsync(
        int iceMapId, string triggeredBy, string? sourceFileStorageKey, int? sourceProfileId,
        LoginDTO login, CancellationToken ct, long? retryOfRunId = null);

    // Advances CURRENTSTAGE as the pipeline progresses through Parse -> MapAndTransform ->
    // Validate -> Commit. The first call for a given run additionally flips STATUS from Queued to
    // Running and stamps STARTEDON (see IceImportRunQB.UPDATE_STAGE).
    Task UpdateStageAsync(long runId, string currentStage, LoginDTO login, CancellationToken ct);

    Task AppendLogAsync(long runId, string logLevel, string message, LoginDTO login, CancellationToken ct);

    // finalStatus must be one of the terminal values CK_TICEIMPORTRUN_STATUS allows: Success |
    // Failed | Cancelled (no PartialFailure in the Phase 0 schema — see IceImportRunBLL's design
    // note on how a partially-successful run is represented).
    Task CompleteRunAsync(
        long runId, string finalStatus, int rowTotalCount, int successCount, int failedCount,
        string? errorMessage, LoginDTO login, CancellationToken ct);

    Task<long> SaveArtifactAsync(long runId, string artifactType, string storageKey, LoginDTO login, CancellationToken ct);

    Task SaveRowResultsAsync(long runId, IEnumerable<IceImportRunRowResultDTO> results, LoginDTO login, CancellationToken ct);

    Task<PagedResult<IceImportRunListItemDTO>> GetHistoryAsync(
        int iceMapId, int page, int pageSize, LoginDTO login, CancellationToken ct);

    Task<IceImportRunDetailDTO?> GetDetailAsync(long runId, LoginDTO login, CancellationToken ct);

    Task<PagedResult<IceImportRunRowResultDTO>> GetRowErrorsAsync(
        long runId, string? status, int page, int pageSize, LoginDTO login, CancellationToken ct);

    // Best-effort cancellation — see IIceImportRunCancellationRegistry's doc comment for the
    // single-instance limitation. Always flips the DB row to 'Cancelled' regardless of whether the
    // in-process signal actually reaches a running background task.
    Task<string> CancelRunAsync(long runId, LoginDTO login, CancellationToken ct);

    Task<IceImportRunDTO?> GetByIdAsync(long runId, LoginDTO login, CancellationToken ct);

    Task<IceImportRunArtifactDTO?> GetArtifactByTypeAsync(
        long runId, string artifactType, LoginDTO login, CancellationToken ct);

    // Creates a new TICEIMPORTRUN row (RetryOfRunId = originalRunId) reusing the original run's
    // "SourceFile" artifact StorageKey, IceMapId, and SourceProfileId. Only allowed when the
    // original run is in a terminal, retryable state (Failed | Cancelled — Success is not
    // retryable, there's nothing to fix). Always re-runs the full pipeline from Parse rather than
    // resuming from the original's CurrentStage — see IceImportRunExecutionService's design note
    // for why (Parse/Map/Validate are cheap relative to Commit, and a partial-resume would require
    // persisting intermediate MappedEntityRowDTO state, which the Phase 0 schema doesn't carry).
    // Returns the new RunId; the caller (RetryImportRun endpoint) is responsible for kicking off the
    // actual background execution, same as CommitImport does for a fresh upload.
    Task<long> PrepareRetryAsync(long originalRunId, LoginDTO login, CancellationToken ct);
}