From f5505190e9065edcb4873e37eb37c5ee3d890fbf Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Tue, 9 Jun 2026 23:20:53 +0200
Subject: [PATCH] Add SignatureDto and mapping for signature handling

Added a new `SignatureDto` record to represent captured signatures with metadata, including properties like `ElementId`, `DataUrl`, `FullName`, `Position`, and `Place`. Updated `SigningCommand` to include a `Signatures` property for handling multiple signatures, deprecating `PsPdfKitAnnotation`.

Introduced a `MappingProfile` class to map `SignatureDto` to `DocReceiverElement` using AutoMapper. Added necessary `using` directives to support the new mapping configuration.
---
 .../Commands/SigningCommand.cs                | 69 +++++++++++++++++++
 .../DocReceiverElements/MappingProfile.cs     | 19 +++++
 2 files changed, 88 insertions(+)
 create mode 100644 EnvelopeGenerator.Application/DocReceiverElements/MappingProfile.cs

diff --git a/EnvelopeGenerator.Application/DocReceiverElements/Commands/SigningCommand.cs b/EnvelopeGenerator.Application/DocReceiverElements/Commands/SigningCommand.cs
index 5c308650..6d1e56fd 100644
--- a/EnvelopeGenerator.Application/DocReceiverElements/Commands/SigningCommand.cs
+++ b/EnvelopeGenerator.Application/DocReceiverElements/Commands/SigningCommand.cs
@@ -5,6 +5,70 @@ 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>
@@ -31,6 +95,11 @@ public record SigningCommand : EnvelopeReceiverQueryBase, IRequest
     /// </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>
diff --git a/EnvelopeGenerator.Application/DocReceiverElements/MappingProfile.cs b/EnvelopeGenerator.Application/DocReceiverElements/MappingProfile.cs
new file mode 100644
index 00000000..84f5c83b
--- /dev/null
+++ b/EnvelopeGenerator.Application/DocReceiverElements/MappingProfile.cs
@@ -0,0 +1,19 @@
+using AutoMapper;
+using EnvelopeGenerator.Application.DocReceiverElements.Commands;
+using EnvelopeGenerator.Domain.Entities;
+
+namespace EnvelopeGenerator.Application.DocReceiverElements;
+
+/// <summary>
+///
+/// </summary>
+public class MappingProfile : Profile
+{
+    /// <summary>
+    ///
+    /// </summary>
+    public MappingProfile()
+    {
+        CreateMap<SignatureDto, DocReceiverElement>();
+    }
+}
\ No newline at end of file