EnvelopeGenerator/EnvelopeGenerator.Application/DocReceiverElements/Commands/SigningCommand.cs

using MediatR;
using EnvelopeGenerator.Application.Common.Dto;
using EnvelopeGenerator.Application.Common.Dto.EnvelopeReceiver;
using EnvelopeGenerator.Application.Common.Query;

namespace EnvelopeGenerator.Application.DocReceiverElements.Commands;

/// <summary>
/// Represents a captured signature with metadata created by the receiver in the signature popup.
/// This model holds the signature image (as base64 data URL) along with signer information
/// used for rendering applied signatures on the PDF canvas.
/// </summary>
/// <remarks>
/// <b>Used in:</b> EnvelopeViewer.razor signature popup workflow
/// <br/>
/// <b>Creation:</b> User draws/types/uploads signature and fills required fields
/// </remarks>
public sealed record SignatureDto
{
    /// <summary>
    /// TBDD_DOCUMENT_RECEIVER_ELEMENT.ID - identifies the specific signature field on the PDF page.
    /// </summary>
    public required int ElementId { get; init; }

    /// <summary>
    /// Base64-encoded data URL of the signature image.
    /// <br/>
    /// <b>Format:</b> <c>data:image/png;base64,iVBORw0KG...</c>
    /// <br/>
    /// <b>Source:</b> Canvas.toDataURL() from signature pad (draw/text/image tabs)
    /// <br/>
    /// <b>Usage:</b> Set as <c>img.src</c> in applied signature overlay
    /// </summary>
    public required string DataUrl { get; init; }

    /// <summary>
    /// Full name of the signer (first and last name).
    /// <br/>
    /// <b>Required:</b> Yes (validated in popup)
    /// <br/>
    /// <b>Example:</b> "Max Mustermann"
    /// </summary>
    public required string FullName { get; init; }

    private readonly string? _position = null;

    /// <summary>
    /// Job title or position of the signer.
    /// <br/>
    /// <b>Required:</b> No (optional field)
    /// <br/>
    /// <b>Example:</b> "Geschäftsführer" or empty string
    /// </summary>
    public string? Position
    {
        get => _position;
        init => _position = string.IsNullOrWhiteSpace(value) ? value : null;
    }

    /// <summary>
    /// Location/place where the signature was created.
    /// <br/>
    /// <b>Required:</b> Yes (validated in popup)
    /// <br/>
    /// <b>Display:</b> Shown with current date in German format (dd.MM.yyyy)
    /// <br/>
    /// <b>Example:</b> "Berlin" ? rendered as "Berlin, 26.01.2025"
    /// </summary>
    public required string Place { get; init; }
}

/// <summary>
/// Command to sign a document by a receiver.
/// </summary>
public record SigningCommand : EnvelopeReceiverQueryBase, IRequest
{
    private EnvelopeReceiverDto? _envelopeReceiver;

    internal void SetEnvelopeReceiver(EnvelopeReceiverDto envelopeReceiver)
    {
        _envelopeReceiver = envelopeReceiver;
    }

    /// <summary>
    /// The envelope receiver information.
    /// </summary>
    public EnvelopeReceiverDto EnvelopeReceiver
    { 
        get => _envelopeReceiver!;
        init => _envelopeReceiver = value;
    }

    /// <summary>
    /// The PSPDFKit annotation data.
    /// </summary>
    [Obsolete("This notification is deprecated. Use Signature.Commands.SignCommand instead.")]
    public PsPdfKitAnnotation? PsPdfKitAnnotation { get; init; }

    /// <summary>
    /// 
    /// </summary>
    public IEnumerable<SignatureDto>? Signatures { get; init; }
}

/// <summary>
/// Handles the sign command. All work is done by pipeline behaviors.
/// This handler is intentionally empty - behaviors handle all the processing.
/// </summary>
public class SignCommandHandler : IRequestHandler<SigningCommand>
{
    /// <summary>
    /// Executes the signing command. Pipeline behaviors handle all processing.
    /// </summary>
    /// <param name="request"></param>
    /// <param name="cancellationToken"></param>
    /// <returns></returns>
    public Task Handle(SigningCommand request, CancellationToken cancellationToken = default)
    {
        return Task.CompletedTask;
    }
}