using GB5Shared.DTO.Framework.Criteria;
using GB5Shared.DTO.Framework.Login;
using PayRollDAL.DTO.Periodic;
using System.Data.Common;
using System.IO;
using System.Threading;
using System.Threading.Tasks;

namespace PayRollBLL.Periodic
{
    public interface IPeriodicBLL
    {
        /// <summary>
        /// Saves or updates a Periodic record. Mirrors GB4 PeriodicBLL.SavePeriodic — see
        /// PeriodicBLL.SavePeriodic for the ported logic and the documented GB5 gaps.
        /// </summary>
        Task<int> SavePeriodic(PeriodicDTO periodicDTO, LoginDTO loginDTO, DbTransaction? sameTransaction = null, CancellationToken ct = default);
        Task<string> GetPeriodicList(
        CriteriaDTO CriteriaDTO, LoginDTO LoginDTO, CancellationToken ct = default);

        /// <summary>
        /// Mirrors GB4 Periodic.svc/GetPeriodic (POST, despite the doc comment) → PeriodicBLL.GetPeriodic
        /// → PeriodicDAL.GetPeriodicDetails. Preserves: mandatory PayConfiguration selection (hard
        /// exception), the IsPartialProcessRequired==0 dispatch to the multi-posting-position
        /// ("New") variant, the 4-flag sort-order if-chain, and the "keep only first PeriodicAddon"
        /// flatten quirk on the standard path. See PeriodicBLL.GetPeriodic for full detail.
        /// </summary>
        Task<(List<PeriodicDTO> Items, int Total)> GetPeriodic(
            int payPeriodId, int firstNumber, int maxResult, CriteriaDTO criteriaDTO, LoginDTO loginDTO, CancellationToken ct = default);

        /// <summary>
        /// Bulk-generates TPERIODIC + TPERIODICADDON rows for every eligible active employee in a
        /// pay period. Mirrors GB4 Periodic.svc/LoadPeriodic (GET) → PeriodicBLL.PeriodicLoad —
        /// see PeriodicBLL.LoadPeriodic for the ported logic and the MTEMP-elimination note.
        /// </summary>
        Task<string> LoadPeriodic(int payPeriodId, int payConfigurationId, LoginDTO loginDTO, CancellationToken ct = default);

        /// <summary>
        /// Mirrors GB4 Periodic.svc/Periodic/Service/Based/Export (POST) →
        /// DumpPerodicServiceBased.PeriodicServiceBasedExport. Builds the export workbook
        /// directly into <paramref name="output"/> (ClosedXML) — see PeriodicBLL for the
        /// GB4 base64-in-JSON → real binary-file-download modernization note. Called with
        /// both real PayPeriodIds and the -1 sentinel by different GB4 callers; -1 is not
        /// special-cased (see PeriodicQB.BuildPeriodicServiceBasedExport's GB4-parity note).
        /// Throws <see cref="System.InvalidOperationException"/> ("There is not entry found
        /// for export..") when the header query returns zero rows, matching GB4's
        /// MethodNotAllowedException.
        /// </summary>
        Task PeriodicServiceBasedExport(
            int payPeriodId, CriteriaDTO criteriaDTO, LoginDTO loginDTO, Stream output, CancellationToken ct = default);
    }
}