using GB5Shared.DTO.Framework.Login;
using RecruitmentDAL.DTO.BgVerification;
using System.Threading;
using System.Threading.Tasks;

namespace RecruitmentBLL.Integration
{
    /// <summary>Outcome of a vendor BG-check call — modeled after IEcpIntegrationService's
    /// EcpCallOutcome pattern. Never throws out to the caller; a failed/unreachable vendor call
    /// degrades to Success=false with an Error, so a vendor outage never breaks
    /// BgVerificationBLL.InitiateBgVerification or the offer-acceptance flow that triggers it.</summary>
    public class BgVendorCallOutcome
    {
        public bool Success { get; set; }
        public string? VendorReference { get; set; }
        public string? Error { get; set; }
    }

    /// <summary>
    /// Placeholder extension point for the formal (vendor-API) side of background verification —
    /// Education/Employment/Criminal checks against a real third-party verification service.
    /// Reference checks do NOT go through this interface — those ride the existing Phase 3 FLS
    /// bridge (RecruitmentFlsActionType.ReferenceCheck) as a human-filled questionnaire; this
    /// interface covers only the system-to-system API half.
    ///
    /// Per the plan (Phase 6): "integration to the actual verification vendor's API is another
    /// GOP Target Operation rather than bespoke per-vendor code" — no vendor has been chosen yet,
    /// so this is a no-op/logging placeholder, not a real HTTP integration. A real implementation
    /// would:
    ///   1. Be registered as a keyed INodeExecutor on GOP's existing extension seam
    ///      (GB5Framework/FrameworkBLL/GOP/Worker/INodeExecutor.cs — e.g.
    ///      services.AddKeyedScoped&lt;INodeExecutor, BgVerificationVendorNodeExecutor&gt;("BgVendorCheck")),
    ///      the same seam ApiCallNodeExecutor/AIExtractNodeExecutor already use, OR call
    ///      out via a plain GopFlow (Source Binding -&gt; Mapper -&gt; Target Operation) the way
    ///      Phase 1's job-board publish does.
    ///   2. POST the candidate's verification-relevant fields (name, DOB, employment history,
    ///      etc. — subject to consent/PII handling, same as every other candidate-data flow in
    ///      this module) to the chosen vendor's API via a named HttpClient
    ///      (IHttpClientFactory, secrets in Vault — never hardcoded).
    ///   3. On the vendor's async webhook/poll completing, update the TBGVERIFICATION row's
    ///      CHECKSTATUS (Passed/Failed/Delayed), VENDORREFERENCE (the vendor's case id), and
    ///      REPORTATTACHMENTID (after uploading the vendor's PDF/JSON report via
    ///      IAttachmentUploadService, same mechanism CandidatePortalBLL.UploadDocumentAsync uses)
    ///      via IBgVerificationBLL.UpdateCheckStatusAsync.
    ///
    /// This placeholder instead: logs the intent, marks the check InProgress (never
    /// Passed/Failed on its own — no real vendor result exists to report), and returns
    /// Success=true with VendorReference=null so InitiateBgVerification can proceed without
    /// blocking on a vendor that doesn't exist yet.
    /// </summary>
    public interface IBgVerificationVendorService
    {
        Task<BgVendorCallOutcome> InitiateVendorCheckAsync(BgVerificationDTO bgVerification, LoginDTO login, CancellationToken ct);
    }
}