using GB5Shared.DTO.Framework.Login;

namespace EntitlementBLL.Onboarding;

/// <summary>
/// Calls SqlWorkbench's real HTTP endpoints (ClientDatabase.svc, ChangeRequest.svc) to
/// provision a new client's physical database. Entitlement never references SwDAL/SwBLL
/// directly — no precedent anywhere in this repo for one module's BLL reaching into another
/// module's project (confirmed: PAY -> Sales/Finance is the only existing cross-module
/// pattern, and it goes over a named HttpClient, not a shared assembly).
/// </summary>
public interface ISqlWorkbenchClient
{
    /// <summary>POST /ClientDatabase/SaveClientDatabase — creates the MSWCLIENTDATABASE row
    /// a ClientProvisioning ChangeRequest will provision. Returns the new ClientDbId.</summary>
    Task<int> SaveClientDatabaseAsync(SwSaveClientDatabaseRequest req, LoginDTO swLogin, CancellationToken ct);

    /// <summary>POST /ChangeRequest/SaveChangeRequest (Draft) — returns the new ChangeRequestId.</summary>
    Task<int> SaveChangeRequestAsync(SwSaveChangeRequestRequest req, LoginDTO swLogin, CancellationToken ct);

    /// <summary>PUT /ChangeRequest/SubmitChangeRequest — Draft -> Submitted.</summary>
    Task SubmitChangeRequestAsync(int changeRequestId, LoginDTO swLogin, CancellationToken ct);

    /// <summary>PUT /ChangeRequest/ApproveChangeRequest — Submitted -> Approved. Only called
    /// in OnboardingApprovalMode.AutoApprove; HumanApprove mode never calls this.</summary>
    Task ApproveChangeRequestAsync(int changeRequestId, string? comment, LoginDTO swLogin, CancellationToken ct);

    /// <summary>POST /ChangeRequest/ExecuteChangeRequest — Approved -> Executed. Only called
    /// in OnboardingApprovalMode.AutoApprove, immediately after ApproveChangeRequestAsync, so
    /// the completion path (the "sqlworkbench.changerequest.executed" Dapr event ->
    /// ResumeAfterProvisioningExecutedAsync) is identical regardless of approval mode — the
    /// only difference is who calls Approve/Execute, not how completion is detected.</summary>
    Task ExecuteChangeRequestAsync(int changeRequestId, LoginDTO swLogin, CancellationToken ct);

    /// <summary>POST /ChangeRequest/QueueChangeRequestExecution — Approved CR is queued for
    /// SqlWorkbench's own background ChangeRequestExecutionWorkerJob instead of run inline on
    /// this HTTP request (tracker §37/§43). Returns immediately; completion is detected the same
    /// way as the AutoApprove/inline path — via the "sqlworkbench.changerequest.executed" Dapr
    /// event (fired on success AND on failure) plus GetChangeRequestStatusAsync's own live
    /// re-check. Used instead of ExecuteChangeRequestAsync so a large baseline-package batch is
    /// never tied to this request's own CancellationToken (§36.13's own proven failure mode).</summary>
    Task QueueChangeRequestExecutionAsync(int changeRequestId, LoginDTO swLogin, CancellationToken ct);

    /// <summary>POST /Provisioning/ProvisionClientDatabase — reapplies an already-Approved/
    /// Released package's scripts to an already-existing client database (tracker §49, Demo
    /// pooled-instance reset). Idempotent (§36's own INSERT...WHERE NOT EXISTS scripts) but does
    /// NOT clear any occupant-written mutable-table data first.</summary>
    Task ReapplyUpgradePackageAsync(int clientDbId, int upgradePackageId, LoginDTO swLogin, CancellationToken ct);

    /// <summary>GET /ChangeRequest/GetChangeRequestById — used by
    /// ResumeAfterProvisioningExecutedAsync to confirm CrStatus == Executed before
    /// continuing, rather than trusting the Dapr event payload's exact shape.</summary>
    Task<SwChangeRequestStatusDTO?> GetChangeRequestStatusAsync(int changeRequestId, LoginDTO swLogin, CancellationToken ct);

    /// <summary>POST /UpgradePackage/GetProvisioningChain — resolves the DbModel's real,
    /// ordered set of Released packages (Universal plus any matching the scope filter),
    /// collapsed to the latest version per supersession chain. Empty list (not an error)
    /// means no packages are registered for this DbModel yet.</summary>
    Task<IReadOnlyList<SwPackageChainItemDTO>> GetProvisioningChainAsync(
        int dbModelId, SwPackageScopeFilterRequest? scope, LoginDTO swLogin, CancellationToken ct);

    /// <summary>GET /ClientDatabase/GetClientDatabaseById — a plain read, already-existing
    /// SqlWorkbench endpoint. Used (tracker §49 Decision 8's corrected design) to resolve a
    /// pooled demo instance's own DatabaseName/ServerConfigId so Entitlement can build a LoginDTO
    /// pointed directly at it and call the real IClientUserProvisioner.ProvisionAsync function —
    /// never a raw table-level INSERT via a bespoke SqlWorkbench endpoint.</summary>
    Task<SwClientDatabaseInfoDTO?> GetClientDatabaseAsync(int clientDbId, LoginDTO swLogin, CancellationToken ct);
}