From dcb3e5d45dcbfc0c9cf829c0f42818e53afa5397 Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Sun, 31 May 2026 11:11:47 +0200
Subject: [PATCH] Mark `Type` obsolete; add `X` and `Y` properties

The `Type` property in `AnnotationCreateDto` was marked as obsolete with the note: "Not required for DevExpress."

Added `X` and `Y` properties to represent the horizontal and vertical positions of the signature field on the page. Both properties use DevExpress units (hundredths of an inch) with the origin at the top-left corner of the page.

Detailed documentation was added for `X` and `Y`, including differences in coordinate systems and unit conversions between DevExpress, PSPDFKit, and GDPicture.
---
 .../Common/Dto/AnnotationDto.cs               | 20 +++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/EnvelopeGenerator.Application/Common/Dto/AnnotationDto.cs b/EnvelopeGenerator.Application/Common/Dto/AnnotationDto.cs
index e20769b5..320d1895 100644
--- a/EnvelopeGenerator.Application/Common/Dto/AnnotationDto.cs
+++ b/EnvelopeGenerator.Application/Common/Dto/AnnotationDto.cs
@@ -35,12 +35,28 @@ public record AnnotationCreateDto
     public string Type { get; init; } = string.Empty;
 
     /// <summary>
-    /// 
+    /// Horizontal position of the signature field on the page.
+    /// <br/><br/>
+    /// <b>DevExpress unit:</b> Hundredths of an inch (1/100 inch ≈ 2.83 PDF points), origin at the <b>top-left</b> corner of the page, X increases to the right.
+    /// <br/>
+    /// <b>Difference from PSPDFKit:</b> PSPDFKit also uses top-left origin but measures in PDF points (1/72 inch).
+    /// To convert: <c>xDevExpress = xPsPdfKit * (100.0 / 72.0)</c>
+    /// <br/>
+    /// <b>Difference from GDPicture:</b> GDPicture uses PDF points with <b>bottom-left</b> origin (standard PDF coordinate system).
+    /// The X axis is the same direction, only unit conversion is needed: <c>xDevExpress = xGdPicture * (100.0 / 72.0)</c>
     /// </summary>
     public double? X { get; init; }
 
     /// <summary>
-    /// 
+    /// Vertical position of the signature field on the page.
+    /// <br/><br/>
+    /// <b>DevExpress unit:</b> Hundredths of an inch (1/100 inch ≈ 2.83 PDF points), origin at the <b>top-left</b> corner of the page, Y increases downward.
+    /// <br/>
+    /// <b>Difference from PSPDFKit:</b> PSPDFKit also uses top-left origin and Y increases downward, but measures in PDF points (1/72 inch).
+    /// To convert: <c>yDevExpress = yPsPdfKit * (100.0 / 72.0)</c>
+    /// <br/>
+    /// <b>Difference from GDPicture:</b> GDPicture uses PDF points with <b>bottom-left</b> origin, so Y increases <b>upward</b> (PDF standard).
+    /// To convert: <c>yDevExpress = (pageHeightInPt - yGdPicture - elementHeightInPt) * (100.0 / 72.0)</c>
     /// </summary>
     public double? Y { get; init; }