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

namespace GB5Shared.FileUpload
{
    /// <summary>
    /// Resolves pre-save attachment uploads (ObjectId=0, TempRefKey set) to their
    /// real entity IDs after the entity save completes.
    ///
    /// MUST be called inside the entity's open DB transaction — after the entity ID
    /// is known, before CommitAsync — so the UPDATE is rolled back automatically if
    /// the entity save fails.
    ///
    /// Header-only (common case):
    ///   if (dto.Attachments != null)
    ///       await _attachmentResolution.ResolveHeaderAsync(
    ///           dto.Attachments, dto.FooId, loginDTO, Trans, ct);
    ///   await _qe.CommitAsync(Trans);
    ///
    /// Multi-level (header + lines):
    ///   if (dto.Attachments != null)
    ///   {
    ///       foreach (var m in dto.Attachments.LevelMappings)
    ///           m.ObjectId = m.TempRefKey.StartsWith("H-") ? dto.HeaderId : lineIdLookup[m.TempRefKey];
    ///       await _attachmentResolution.ResolveAsync(dto.Attachments, loginDTO, Trans, ct);
    ///   }
    ///   await _qe.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);
    }
}