using System.Data.Common;
using System.Threading;
using System.Threading.Tasks;
using FrameworkDAL.DTO.ECM;
using GB5Shared.DTO.Framework.Login;

namespace FrameworkBLL.Attachment
{
    /// <summary>
    /// Resolves pre-save attachment uploads to their real entity IDs.
    ///
    /// Call inside the entity's open DB transaction (after ExecuteSaveAsync,
    /// before CommitAsync) so resolution is rolled back if the entity save fails.
    ///
    /// Usage — header-only form (common case):
    ///   if (attachments != null)
    ///       await _attachmentResolution.ResolveHeaderAsync(
    ///           attachments, dto.FooId, loginDTO, Trans, ct);
    ///   await _QueryExecutor.CommitAsync(Trans);
    ///
    /// Usage — multi-level form (header + lines):
    ///   if (attachments != null)
    ///   {
    ///       // Caller populates ObjectId per level before calling
    ///       foreach (var m in attachments.LevelMappings)
    ///           m.ObjectId = m.TempRefKey.StartsWith("H-") ? dto.HeaderId : lineIdLookup[m.TempRefKey];
    ///       await _attachmentResolution.ResolveAsync(attachments, loginDTO, Trans, ct);
    ///   }
    ///   await _QueryExecutor.CommitAsync(Trans);
    /// </summary>
    public interface IAttachmentResolutionService
    {
        /// <summary>
        /// Full multi-level resolve.
        /// ObjectId must be set on every LevelAttachmentMap before calling.
        /// </summary>
        Task ResolveAsync(
            AttachmentResolutionEnvelope envelope,
            LoginDTO login,
            DbTransaction tx,
            CancellationToken ct = default);

        /// <summary>
        /// Convenience wrapper for the common header-only case.
        /// Sets ObjectId = entityId on all LevelMappings and calls ResolveAsync.
        /// </summary>
        Task ResolveHeaderAsync(
            AttachmentResolutionEnvelope envelope,
            int entityId,
            LoginDTO login,
            DbTransaction tx,
            CancellationToken ct = default);
    }
}