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

namespace RecruitmentBLL.CandidateDemographic
{
    // CRUD for MCANDIDATEDEMOGRAPHIC — upsert-by-CandidateId (one row per Candidate; see
    // CandidateDemographicDTO's doc comment). Primary caller is RecruitmentFlsBridgeBLL's
    // VoluntarySelfId submit handler; this BLL exists so that call routes through the exact same
    // CLAUDE.md-compliant ExecuteSaveAsync pipeline as every other Recruitment entity, instead of
    // the bridge hand-rolling persistence.
    //
    // ── DELIBERATELY NO GetCandidateDemographic(int CandidateId) METHOD HERE ──
    // This table's only sanctioned bulk-read path is the aggregated, cell-suppressed
    // DeiSourcingReport (RecruitmentBLL.Reports.DeiSourcingReport). A generic "get this
    // candidate's demographic row" method is intentionally omitted from this interface — do NOT
    // add one and do NOT surface individual GenderIdentity/EthnicityRace/DisabilityStatus/
    // VeteranStatus/AgeBand values in any candidate/application detail view, admin screen, or
    // ad hoc query. If a future admin/compliance need genuinely requires reading one candidate's
    // row (e.g. a data-subject access request), gate it explicitly as admin/compliance-only, log
    // the access, and re-read this comment plus the migration header before adding it — the safe
    // default for this pass is "no individual-record read path exists at all".
    public interface ICandidateDemographicBLL
    {
        // Upserts by CandidateId. Enforces the consent guard (see implementation doc comment) —
        // callers must never rely on this method persisting populated demographic fields unless
        // dto.ConsentToCollect is explicitly true on input.
        Task<string> SaveCandidateDemographic(CandidateDemographicDTO CandidateDemographicDTO, LoginDTO LoginDTO, CancellationToken ct);

        // Soft-delete via STATUS=2 — not currently called from the FLS bridge; provided for
        // CLAUDE.md CRUD-completeness / a future compliance withdrawal flow.
        Task<string> DeleteCandidateDemographic(int CandidateDemographicId, LoginDTO LoginDTO, CancellationToken ct);
    }
}