Add signature workflow models, services, and configurations
Introduced new models (`SignatureDto`, `SignatureCaptureDto`, `EnvelopeReceiverDto`) to support a signature-based workflow. Added services for handling API interactions (`SignatureService`, `AuthService`, `DocumentService`, `EnvelopeReceiverService`, `SignatureCacheService`). Enhanced configuration with `ApiOptions` and `PdfViewerOptions`. Integrated DevExpress features with custom data connection providers, in-memory report storage, and font loading utilities. Marked `AnnotationDto` and `AnnotationService` as `[Obsolete]` in favor of newer implementations. Added detailed documentation for coordinate systems, unit conversions, and usage scenarios.
This commit is contained in:
@@ -0,0 +1,32 @@
|
||||
namespace EnvelopeGenerator.WebUI.Client.Models;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a pre-assigned signature annotation position on a specific page.
|
||||
/// <br/><br/>
|
||||
/// <b>Coordinate unit (X, Y):</b> Inches (GdPicture14 native unit),
|
||||
/// origin at the <b>top-left</b> corner of the page, both axes increase downward/rightward.
|
||||
/// <br/><br/>
|
||||
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
|
||||
/// Convert: <c>xDX = xInches * 100.0</c>
|
||||
/// <br/>
|
||||
/// <b>Conversion to PDF Points:</b> Multiply by 72 (1 inch = 72 points).
|
||||
/// Convert: <c>xPt = xInches * 72.0</c>
|
||||
/// <br/>
|
||||
/// <b>Y-axis for PDF (bottom-left origin):</b> Flip required for iText7.
|
||||
/// Convert: <c>yPt = (pageHeightInches - yInches - elemHeightInches) * 72.0</c>
|
||||
/// </summary>
|
||||
[Obsolete("Use SignatureDto with SignatureService.")]
|
||||
public record AnnotationDto
|
||||
{
|
||||
/// <summary>Unique identifier of the annotation.</summary>
|
||||
public long Id { get; init; }
|
||||
|
||||
/// <summary>1-based page number within the document.</summary>
|
||||
public int Page { get; init; }
|
||||
|
||||
/// <summary>Horizontal position in INCHES from the left edge of the page.</summary>
|
||||
public double X { get; init; }
|
||||
|
||||
/// <summary>Vertical position in INCHES from the top edge of the page.</summary>
|
||||
public double Y { get; init; }
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
namespace EnvelopeGenerator.WebUI.Client.Models.Constants
|
||||
{
|
||||
public enum SenderAppType
|
||||
{
|
||||
LegacyFormApp = 0,
|
||||
ReceiverUIBlazorApp = 1
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
namespace EnvelopeGenerator.WebUI.Client.Models.Constants;
|
||||
|
||||
/// <summary>
|
||||
/// Represents the unit of measurement for coordinate values in signature positioning.
|
||||
/// Used for converting coordinates between different systems (GdPicture14, PDF.js, iText7).
|
||||
/// </summary>
|
||||
public enum UnitOfLength
|
||||
{
|
||||
/// <summary>
|
||||
/// Inch unit (1 inch = 25.4 mm).
|
||||
/// This is the native unit used by GdPicture14 (EnvelopeGenerator.Form - Legacy VB.NET app).
|
||||
/// Database stores all coordinates (X, Y, Width, Height) in INCHES.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <b>Source:</b> GdPicture14.Annotations.AnnotationStickyNote uses INCHES natively.
|
||||
/// <br/>
|
||||
/// <b>Evidence:</b> VB.NET code directly assigns database values to annotation properties without conversion:
|
||||
/// <code>
|
||||
/// oAnnotation.Left = CSng(pElement.X) ' Direct assignment ? INCHES
|
||||
/// oAnnotation.Top = CSng(pElement.Y)
|
||||
/// </code>
|
||||
/// <b>Standard Page Dimensions:</b>
|
||||
/// <list type="bullet">
|
||||
/// <item>A4: 8.27" × 11.69" (210mm × 297mm)</item>
|
||||
/// <item>Letter: 8.5" × 11"</item>
|
||||
/// </list>
|
||||
/// </remarks>
|
||||
Inch = 0,
|
||||
|
||||
/// <summary>
|
||||
/// PDF Point unit (1 point = 1/72 inch).
|
||||
/// This is the standard unit used by PDF specification and PDF.js viewer.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <b>Definition:</b> According to PDF specification and Microsoft documentation:
|
||||
/// <br/>
|
||||
/// <i>"PDF pages are sized in point units. 1 pt == 1/72 inch"</i>
|
||||
/// <br/><br/>
|
||||
/// <b>Conversion Formula:</b>
|
||||
/// <code>
|
||||
/// points = inches * 72.0
|
||||
/// inches = points / 72.0
|
||||
/// </code>
|
||||
/// <b>Important:</b> Point ? Pixel!
|
||||
/// <list type="bullet">
|
||||
/// <item><b>Point (pt):</b> Device-independent unit (always 1/72 inch)</item>
|
||||
/// <item><b>Pixel (px):</b> Device-dependent unit (varies with screen DPI)</item>
|
||||
/// <item>At 72 DPI: 1 point = 1 pixel (coincidence)</item>
|
||||
/// <item>At 96 DPI: 1 point ? 1.33 pixels</item>
|
||||
/// <item>At 300 DPI: 1 point ? 4.17 pixels</item>
|
||||
/// </list>
|
||||
/// <b>Standard Page Dimensions (in points):</b>
|
||||
/// <list type="bullet">
|
||||
/// <item>A4: 595 × 842 points (8.27" × 11.69" × 72)</item>
|
||||
/// <item>Letter: 612 × 792 points (8.5" × 11" × 72)</item>
|
||||
/// </list>
|
||||
/// <b>Usage in EnvelopeGenerator:</b>
|
||||
/// <list type="bullet">
|
||||
/// <item>PDF.js viewer expects coordinates in points</item>
|
||||
/// <item>iText7 library uses points for PDF manipulation</item>
|
||||
/// <item>PSPDFKit (Web) uses points for annotation placement</item>
|
||||
/// </list>
|
||||
/// </remarks>
|
||||
Point
|
||||
}
|
||||
@@ -0,0 +1,105 @@
|
||||
namespace EnvelopeGenerator.WebUI.Client.Models;
|
||||
|
||||
/// <summary>
|
||||
/// Client-side model for the envelope receiver returned by
|
||||
/// <c>GET api/EnvelopeReceiver/{envelopeKey}</c>.
|
||||
/// </summary>
|
||||
public record EnvelopeReceiverDto
|
||||
{
|
||||
public int EnvelopeId { get; init; }
|
||||
public int ReceiverId { get; init; }
|
||||
public int Sequence { get; init; }
|
||||
|
||||
public string? Name { get; init; }
|
||||
public string? JobTitle { get; init; }
|
||||
public string? CompanyName { get; init; }
|
||||
public string? PrivateMessage { get; init; }
|
||||
|
||||
public DateTime AddedWhen { get; init; }
|
||||
public DateTime? ChangedWhen { get; init; }
|
||||
public bool HasPhoneNumber { get; init; }
|
||||
|
||||
public EnvelopeClientDto? Envelope { get; init; }
|
||||
public ReceiverClientDto? Receiver { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Client-side model for the envelope data embedded in <see cref="EnvelopeReceiverDto"/>.
|
||||
/// </summary>
|
||||
public record EnvelopeClientDto
|
||||
{
|
||||
public int Id { get; init; }
|
||||
public int UserId { get; init; }
|
||||
public int Status { get; init; }
|
||||
public string StatusName { get; init; } = string.Empty;
|
||||
public string Uuid { get; init; } = string.Empty;
|
||||
public string Title { get; init; } = string.Empty;
|
||||
public string Message { get; init; } = string.Empty;
|
||||
public DateTime AddedWhen { get; init; }
|
||||
public DateTime? ChangedWhen { get; init; }
|
||||
public string Language { get; init; } = "de-DE";
|
||||
public int? EnvelopeTypeId { get; init; }
|
||||
public string? EnvelopeTypeTitle { get; init; }
|
||||
public int? ContractType { get; init; }
|
||||
public int? CertificationType { get; init; }
|
||||
public bool UseAccessCode { get; init; }
|
||||
public bool TFAEnabled { get; init; }
|
||||
public IEnumerable<DocumentClientDto>? Documents { get; init; }
|
||||
public EnvelopeSenderDto? User { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Sender (user) information embedded in <see cref="EnvelopeClientDto"/>.
|
||||
/// </summary>
|
||||
public record EnvelopeSenderDto
|
||||
{
|
||||
public int Id { get; init; }
|
||||
public string? Username { get; init; }
|
||||
public string? FullName { get; init; }
|
||||
public string? Email { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Client-side model for a document embedded in <see cref="EnvelopeClientDto"/>.
|
||||
/// </summary>
|
||||
public record DocumentClientDto
|
||||
{
|
||||
public int Id { get; init; }
|
||||
public int EnvelopeId { get; init; }
|
||||
public DateTime AddedWhen { get; init; }
|
||||
public IEnumerable<SignatureClientDto>? Elements { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Client-side model for a signature/annotation element embedded in <see cref="DocumentClientDto"/>.
|
||||
/// </summary>
|
||||
public record SignatureClientDto
|
||||
{
|
||||
public int Id { get; init; }
|
||||
public int DocumentId { get; init; }
|
||||
public int ReceiverId { get; init; }
|
||||
public int ElementType { get; init; }
|
||||
public double X { get; init; }
|
||||
public double Y { get; init; }
|
||||
public double Width { get; init; }
|
||||
public double Height { get; init; }
|
||||
public int Page { get; init; }
|
||||
public bool Required { get; init; }
|
||||
public string? Tooltip { get; init; }
|
||||
public bool ReadOnly { get; init; }
|
||||
public int AnnotationIndex { get; init; }
|
||||
public DateTime AddedWhen { get; init; }
|
||||
public DateTime? ChangedWhen { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Client-side model for the receiver data embedded in <see cref="EnvelopeReceiverDto"/>.
|
||||
/// </summary>
|
||||
public record ReceiverClientDto
|
||||
{
|
||||
public int Id { get; init; }
|
||||
public string? EmailAddress { get; init; }
|
||||
public string? Signature { get; init; }
|
||||
public DateTime AddedWhen { get; init; }
|
||||
public DateTime? TfaRegDeadline { get; init; }
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
namespace EnvelopeGenerator.WebUI.Client.Models;
|
||||
|
||||
/// <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
|
||||
/// <br/>
|
||||
/// <b>Storage:</b> Session-only (Blazor component state, lost on page refresh)
|
||||
/// <br/>
|
||||
/// <b>Rendering:</b> Applied signatures display: Image + Separator + Name/Position/Place/Date
|
||||
/// </remarks>
|
||||
public sealed record SignatureCaptureDto
|
||||
{
|
||||
/// <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)
|
||||
/// <b>Display:</b> Bold text in applied signature block
|
||||
/// <br/>
|
||||
/// <b>Example:</b> "Max Mustermann"
|
||||
/// </summary>
|
||||
public required string FullName { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Job title or position of the signer.
|
||||
/// <br/>
|
||||
/// <b>Required:</b> No (optional field)
|
||||
/// <br/>
|
||||
/// <b>Display:</b> Normal weight text between name and place/date
|
||||
/// <br/>
|
||||
/// <b>Example:</b> "Geschäftsführer" or empty string
|
||||
/// </summary>
|
||||
public string Position { get; init; } = string.Empty;
|
||||
|
||||
/// <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; }
|
||||
}
|
||||
@@ -0,0 +1,101 @@
|
||||
using EnvelopeGenerator.WebUI.Client.Models.Constants;
|
||||
|
||||
namespace EnvelopeGenerator.WebUI.Client.Models;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a signature position on a PDF page.
|
||||
/// Coordinates stored in INCHES (GdPicture14 native unit).
|
||||
/// Origin: Top-left corner, X increases right, Y increases down.
|
||||
/// </summary>
|
||||
public class SignatureDto
|
||||
{
|
||||
/// <summary>Unique identifier.</summary>
|
||||
public int Id { get; init; }
|
||||
|
||||
private double _x;
|
||||
private double _y;
|
||||
|
||||
/// <summary>Horizontal position in INCHES from left edge.</summary>
|
||||
public double X
|
||||
{
|
||||
get => _x * Factor;
|
||||
init => _x = value;
|
||||
}
|
||||
|
||||
/// <summary>Vertical position in INCHES from top edge.</summary>
|
||||
public double Y
|
||||
{
|
||||
get => _y * Factor;
|
||||
init => _y = value;
|
||||
}
|
||||
|
||||
/// <summary>1-based page number.</summary>
|
||||
public int Page { get; init; }
|
||||
|
||||
/// <summary>Sender application type that created this signature.</summary>
|
||||
public SenderAppType SenderAppType { get; init; }
|
||||
|
||||
private UnitOfLength _unitOfLength;
|
||||
|
||||
public SignatureDto Convert(UnitOfLength unitOfLength)
|
||||
{
|
||||
_unitOfLength = unitOfLength;
|
||||
return this;
|
||||
}
|
||||
|
||||
public double Factor
|
||||
{
|
||||
get
|
||||
{
|
||||
if (SenderAppType != SenderAppType.LegacyFormApp)
|
||||
{
|
||||
throw new NotImplementedException(
|
||||
$"SenderAppType '{SenderAppType}' is not yet implemented. " +
|
||||
$"Currently, only '{nameof(SenderAppType.LegacyFormApp)}' is supported. " +
|
||||
$"Future implementations will handle '{nameof(SenderAppType.ReceiverUIBlazorApp)}' and other types.");
|
||||
}
|
||||
|
||||
// LegacyFormApp uses GdPicture14 with INCHES
|
||||
return _unitOfLength switch
|
||||
{
|
||||
UnitOfLength.Inch => 1.0, // No conversion needed: INCHES ? INCHES
|
||||
UnitOfLength.Point => 72.0, // INCHES ? PDF Points: 1 inch = 72 points (PDF standard, NOT pixels!)
|
||||
_ => throw new InvalidOperationException(
|
||||
$"Unknown UnitOfLength: {_unitOfLength}. Expected '{nameof(UnitOfLength.Inch)}' or '{nameof(UnitOfLength.Point)}'.")
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public static class SignatureDtoExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Converts all signatures in the collection to the specified unit of length.
|
||||
/// </summary>
|
||||
/// <typeparam name="T">Type of the collection (IEnumerable, List, etc.)</typeparam>
|
||||
/// <param name="signatures">Collection of SignatureDto objects to convert.</param>
|
||||
/// <param name="unitOfLength">Target unit of measurement (Inch or Point).</param>
|
||||
/// <returns>The same collection with all signatures converted to the specified unit.</returns>
|
||||
/// <exception cref="ArgumentNullException">Thrown when signatures collection is null.</exception>
|
||||
/// <remarks>
|
||||
/// <b>Usage:</b>
|
||||
/// <code>
|
||||
/// var signatures = await SignatureService.GetAsync(envelopeKey);
|
||||
/// var convertedSignatures = signatures.ConvertAll(UnitOfLength.Point);
|
||||
/// </code>
|
||||
/// <b>Note:</b> This method modifies each SignatureDto object in place and returns the same collection.
|
||||
/// </remarks>
|
||||
public static T Convert<T>(this T signatures, UnitOfLength unitOfLength)
|
||||
where T : IEnumerable<SignatureDto>
|
||||
{
|
||||
if (signatures == null)
|
||||
throw new ArgumentNullException(nameof(signatures));
|
||||
|
||||
foreach (var signature in signatures)
|
||||
{
|
||||
signature.Convert(unitOfLength);
|
||||
}
|
||||
|
||||
return signatures;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user