Update solution items in EnvelopeGenerator.sln

Replaced `COPILOT_CONTEXT_EN.md` with `COPILOT_CONTEXT.md` in the `ProjectSection(SolutionItems)` of the solution file `EnvelopeGenerator.sln` to reflect updated documentation.
2026-06-11 11:38:59 +02:00
parent 26da78fa22
commit 6d1fb05e10
2 changed files with 1 additions and 1 deletions
--- a/COPILOT_CONTEXT.md
+++ b/COPILOT_CONTEXT.md
@@ -0,0 +1,424 @@
+# EnvelopeGenerator — AI Context Reference
+
+## Purpose
+Digital document signing system with **unified Blazor WASM frontend** for both Senders and Receivers. Senders create envelopes and place signature fields. Receivers view PDFs, sign documents, export stamped PDFs.
+
+**Primary Libraries:** DevExpress + PDF.js (PSPDFKit removed)
+
+---
+
+## Deployment Architecture
+
+**Two Presentation Projects (Both Required):**
+
+1. **EnvelopeGenerator.API** (ASP.NET Core Web API)
+   - Runs independently (development & production)
+   - **YARP Reverse Proxy** configured via `yarp.json`
+   - Proxies requests to:
+     - `EnvelopeGenerator.ReceiverUI` (Blazor WASM)
+     - External Auth.API service
+   - Serves as single entry point for all requests
+
+2. **EnvelopeGenerator.ReceiverUI** (Blazor WebAssembly)
+   - Runs on separate host/port
+   - Accessed **only through API proxy** (not directly)
+   - Serves static files (HTML, JS, CSS, WASM)
+
+**Request Flow:**
+```
+Client ? API:8088 (YARP Proxy) ? ReceiverUI:52936 (Blazor WASM)
+                                ? Auth.API:9090 (External Auth Service)
+```
+
+**Configuration:** `EnvelopeGenerator.API/yarp.json`
+
+---
+
+## ReceiverUI Route Structure
+
+### Root Route
+| Route | File | Purpose |
+|---|---|---|
+| `/` | `Index.razor` | Application entry point (landing page). |
+
+### Sender Routes
+| Route | File | Purpose |
+|---|---|---|
+| `/sender/login` | `LoginSenderPage.razor` | Username/password authentication |
+| `/sender` | `EnvelopeSenderPage.razor` | Sender dashboard (envelope list) |
+
+### Receiver Routes
+| Route | File | Purpose |
+|---|---|---|
+| `/envelope/login/{EnvelopeKey}` | `LoginReceiverPage.razor` | Access code authentication for specific envelope |
+| `/envelope/{EnvelopeKey}` | `EnvelopeReceiverPage.razor` | View & sign envelope (PDF.js viewer) |
+
+**Multi-Envelope Support:** Receivers can login to multiple envelopes simultaneously (per-envelope cookie authentication).
+
+---
+
+## Architecture Evolution
+
+### Old Architecture (Deprecated)
+- **Sender UI:** `EnvelopeGenerator.Web` (Razor Pages + PSPDFKit)
+- **Receiver UI:** `EnvelopeGenerator.ReceiverUI` (Blazor WASM + PDF.js)
+- **Backend:** `EnvelopeGenerator.API`
+
+### Current Architecture
+- **Unified Frontend:** `EnvelopeGenerator.ReceiverUI` (Blazor WASM) — **Both Senders & Receivers**
+- **Backend:** `EnvelopeGenerator.API` — **Both Senders & Receivers**
+- **Libraries:** DevExpress + PDF.js
+- **PSPDFKit:** **REMOVED**
+
+---
+
+## Solution Structure
+
+| Project | Target | Purpose |
+|---|---|---|
+| `EnvelopeGenerator.API` | net8.0 | ASP.NET Core Web API. Backend for **both Senders & Receivers**. Auth, PDF serving, signature endpoints. |
+| `EnvelopeGenerator.ReceiverUI` | net8.0 WASM | **Unified Blazor WebAssembly Frontend**. UI for **both Senders & Receivers**. YARP proxy to API. |
+| `EnvelopeGenerator.Web` | net7/8/9 | **DEPRECATED.** Legacy Razor Pages (Sender UI). No longer used. |
+| `EnvelopeGenerator.Application` | multi | MediatR CQRS handlers. Business logic. |
+| `EnvelopeGenerator.Domain` | multi | Domain models, constants, interfaces. |
+| `EnvelopeGenerator.Infrastructure` | multi | EF Core repos, DB context. |
+| `EnvelopeGenerator.PdfEditor` | multi | iText7 utilities (NOT used in ReceiverUI). |
+| `EnvelopeGenerator.DependencyInjection` | multi | DI registration helpers. |
+| **VB.NET projects** (Service/Form/BBTests) | net462 | **Legacy. Do NOT touch.** |
+
+---
+
+## Key Files & Routes
+
+| File | Route/Purpose |
+|---|---|
+| `ReceiverUI/Pages/Index.razor` | `/` — Application entry point (landing page). |
+| `ReceiverUI/Pages/EnvelopeSenderPage.razor` | `/sender` — Sender dashboard (envelope list). |
+| `ReceiverUI/Pages/EnvelopeReceiverPage.razor` | `/envelope/{key}` — Receiver PDF viewer & signing. |
+| `ReceiverUI/Pages/LoginSenderPage.razor` | `/sender/login` — Sender username/password auth. |
+| `ReceiverUI/Pages/LoginReceiverPage.razor` | `/envelope/login/{EnvelopeKey}` — Receiver access code auth. |
+| `ReceiverUI/wwwroot/js/pdf-viewer.js` | PDF.js wrapper (zoom, pagination, thumbnails). |
+| `ReceiverUI/wwwroot/js/receiver-signature.js` | Signature pad (draw/type/image). |
+| `ReceiverUI/wwwroot/css/envelope-viewer.css` | EnvelopeViewer styles. |
+| `ReceiverUI/Services/AuthService.cs` | Receiver + Sender authentication. |
+| `ReceiverUI/Services/SignatureCacheService.cs` | Signature caching (Redis/SQL). |
+| `API/Controllers/CacheController.cs` | Signature cache endpoints. |
+
+---
+
+## Coordinate System — CRITICAL
+
+**Database Format:** INCHES (GdPicture14 native)  
+**Origin:** Top-left corner  
+**Axes:** X right, Y down
+
+### Conversion Formulas
+
+| From INCHES to | Formula | Example |
+|---|---|---|
+| **DevExpress DX** | `x_DX = x_inches * 100` | 1.5" ? 150 DX |
+| **PDF Points** | `x_pt = x_inches * 72` | 1.5" ? 108 pt |
+| **PDF.js Pixels** | Normalize ? scale | `(x_inches / pageWidth) * canvasWidth * scale` |
+
+**A4 Dimensions:**
+- Width: 8.27" = 595pt = 827 DX
+- Height: 11.69" = 842pt = 1169 DX
+
+### Unit Systems
+
+| System | Unit | Origin | Y-Axis |
+|---|---|---|---|
+| **Database (GdPicture14)** | Inches | Top-left | Down |
+| PDF.js | Pixels | Top-left | Down |
+| iText7 PDF | Points (1/72") | **Bottom-left** | **Up** (flip required) |
+| ~~PSPDFKit~~ | ~~Points~~ | ~~Top-left~~ | **REMOVED** |
+
+---
+
+## EnvelopeReceiver — PDF.js Viewer & Signing
+
+**Route:** `/envelope/{EnvelopeKey}`  
+**Tech:** PDF.js 3.11.174 + Blazor WASM + configurable quality  
+**File:** `ReceiverUI/Pages/EnvelopeReceiverPage.razor`
+
+### Key Features
+1. HiDPI/Retina support (4x quality)
+2. Configurable quality (`appsettings.json`)
+3. Unlimited zoom (50%-300%)
+4. Ctrl+Wheel global zoom
+5. Resizable thumbnail sidebar (150-400px, localStorage)
+6. Responsive (desktop/mobile)
+
+### Configuration
+**File:** `ReceiverUI/wwwroot/appsettings.json`
+
+```json
+{
+  "PdfViewer": {
+    "ThumbnailBaseScale": 0.75,
+    "ThumbnailEnableHiDPI": true,
+    "MainCanvasEnableHiDPI": true,
+    "ZoomStepPercentage": 5
+  }
+}
+```
+
+### JavaScript API
+**File:** `ReceiverUI/wwwroot/js/pdf-viewer.js`
+
+```javascript
+window.pdfViewer = {
+    initialize(canvasId, pdfDataUrl, dotNetRef),
+    renderPage(num),
+    renderSignatureButtons(signatures, pageNum, dotNetRef),
+    applySignature(signatureId, dataUrl, fullName, position, place),
+    zoomIn(), zoomOut(), dispose()
+}
+```
+
+---
+
+## Signature Workflow — EnvelopeReceiver
+
+**IMPORTANT:** iText7 NOT used (GPL license issue). Client-side overlay system only.
+
+### Workflow Steps
+
+1. **Page Load:**
+   - Check `SignatureCacheService` for cached signature
+   - If cached ? skip popup, load signature
+   - If not ? show automatic popup (mandatory)
+
+2. **Signature Popup (DxPopup):**
+   - **Cannot close** (no X, no ESC, no outside-click)
+   - **3 Tabs:** Draw (canvas) / Text (font select) / Image (upload)
+   - **Required:** Full name, Place
+   - **Optional:** Position
+   - **Save ?** Store in `_capturedSignature`, cache via API
+
+3. **Signature Buttons:**
+   - Render purple "Unterschreiben" buttons at signature field positions
+   - Coordinates: INCHES ? POINTS ? Pixels (scaled)
+   - File: `pdf-viewer.js` ? `renderSignatureButtons()`
+
+4. **Apply Signature (Click "Unterschreiben"):**
+   - JS: Remove button, create HTML overlay
+   - Format: Image + separator + text (Name, Position, Place, Date)
+   - **NOT stamped on PDF bytes** (visual overlay only)
+
+5. **Re-rendering:**
+   - Zoom/Page change ? recalculate button positions
+   - Session state: `_capturedSignature` (lost on refresh)
+
+### Data Model
+**File:** `ReceiverUI/Models/SignatureCaptureDto.cs`
+
+```csharp
+public sealed record SignatureCaptureDto {
+    public required string DataUrl { get; init; }    // base64 PNG
+    public required string FullName { get; init; }
+    public string Position { get; init; } = "";      // Optional
+    public required string Place { get; init; }
+}
+```
+
+---
+
+## Signature Caching
+
+**Purpose:** Persist signature across page refreshes (distributed cache: Redis/SQL)
+
+### API Endpoints
+**Controller:** `API/Controllers/CacheController.cs`
+
+- `POST /api/Cache/SignatureCapture/{envelopeKey}` — Save
+- `GET /api/Cache/SignatureCapture/{envelopeKey}` — Load
+- `DELETE /api/Cache/SignatureCapture/{envelopeKey}` — Delete
+
+**Cache Key Format:**
+```
+signature:91751687-8ae6-4777-bf5f-b8846085e62e:{envelopeKey}
+```
+
+**Configuration:** `appsettings.json`
+```json
+{
+  "Cache": {
+    "SignatureCacheExpiration": null  // or "02:00:00" for 2h
+  }
+}
+```
+
+### Service
+**File:** `ReceiverUI/Services/SignatureCacheService.cs`
+
+```csharp
+public class SignatureCacheService {
+    Task SaveSignatureAsync(string envelopeKey, SignatureCaptureDto signature);
+    Task<SignatureCaptureDto?> GetSignatureAsync(string envelopeKey);
+    Task DeleteSignatureAsync(string envelopeKey);
+}
+```
+
+**Error Handling:** Fire-and-forget saves, graceful degradation on load failure.
+
+---
+
+## Sender Login
+
+**Route:** `/sender/login`  
+**File:** `ReceiverUI/Pages/LoginSenderPage.razor`  
+**Tech:** Bootstrap 5 + DevExpress Blazing Berry theme
+
+### AuthService Extension
+**File:** `ReceiverUI/Services/AuthService.cs`
+
+```csharp
+public enum SenderLoginResult { Success, InvalidCredentials, Error }
+
+public async Task<SenderLoginResult> LoginSenderAsync(string username, string password) {
+    var response = await http.PostAsJsonAsync(
+        $"{_api.BaseUrl}/api/auth?cookie=true",
+        new { username, password });
+    
+    return response.StatusCode switch {
+        HttpStatusCode.OK => SenderLoginResult.Success,
+        HttpStatusCode.Unauthorized => SenderLoginResult.InvalidCredentials,
+        _ => SenderLoginResult.Error
+    };
+}
+```
+
+### API Integration
+**Endpoint:** `POST /api/auth?cookie=true`
+
+**Request:**
+```json
+{ "username": "TekH", "password": "***" }
+```
+
+**Response:**
+- `200 OK` ? Cookie set, redirect to `/sender`
+- `401 Unauthorized` ? Show error: "Ungültige Anmeldedaten"
+- Other ? Show error: "Serverfehler"
+
+**Cookie:** HTTP-only, Secure (HTTPS), SameSite=Strict
+
+### UI Flow
+1. User enters username + password
+2. Click "Anmelden" or press Enter
+3. Call `AuthService.LoginSenderAsync()`
+4. Success ? `Navigation.NavigateTo("/sender", forceLoad: true)`
+5. Error ? Display alert
+
+---
+
+## Receiver Login
+
+**Route:** `/envelope/login/{EnvelopeKey}`  
+**File:** `ReceiverUI/Pages/LoginReceiverPage.razor`
+
+**Multi-Envelope Support:** Cookies are stored per-envelope (e.g., `AuthTokenSignFLOWReceiver.{envelopeKey}`), allowing simultaneous authentication for multiple envelopes in the same browser session.
+
+### AuthService Method
+```csharp
+public enum EnvelopeLoginResult { Success, InvalidCode, NotFound, Error }
+
+public async Task<EnvelopeLoginResult> LoginEnvelopeReceiverAsync(string key, string accessCode) {
+    var form = new MultipartFormDataContent();
+    form.Add(new StringContent(accessCode), "AccessCode");
+    
+    var response = await http.PostAsync(
+        $"{_api.BaseUrl}/api/Auth/envelope-receiver/{Uri.EscapeDataString(key)}", form);
+    
+    return response.StatusCode switch {
+        HttpStatusCode.OK => EnvelopeLoginResult.Success,
+        HttpStatusCode.Unauthorized => EnvelopeLoginResult.InvalidCode,
+        HttpStatusCode.NotFound => EnvelopeLoginResult.NotFound,
+        _ => EnvelopeLoginResult.Error
+    };
+}
+```
+
+**Success:** Redirect to `/envelope/{key}`
+
+---
+
+## NuGet Packages (ReceiverUI)
+
+| Package | Version | Purpose |
+|---|---|---|
+| `DevExpress.Blazor.*` | 25.2.3 | UI components (grids, popups, etc.) |
+| `SkiaSharp.*` | 3.119.1 | WASM rendering |
+| ~~`itext`~~ | ~~8.0.5~~ | **NOT USED** (GPL license) |
+
+**External CDN:**
+- PDF.js 3.11.174: `https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js`
+
+---
+
+## Mistakes History — Do NOT Repeat
+
+| Mistake | Why Wrong |
+|---|---|
+| Using iText7 in EnvelopeReceiver | GPL license issue. Use overlay system instead. |
+| Using PSPDFKit | Removed from architecture. Use PDF.js + DevExpress. |
+| Hardcoded quality values in PDF.js | Use `appsettings.json` for configurability. |
+| Complex toolbar layouts | User wants simplicity. Keep horizontal layout. |
+| Over-designed UI (gradients/badges) | User prefers simple text labels. |
+| Ignoring "revert" instructions | Revert HTML structure, not just CSS. |
+| `BottomMarginBand` for signatures | Repeats on every page. Use DetailBand. |
+| `imageY = (page-1) * 1169 + ann.Y` | Inflates DetailBand. Calculate per-page. |
+
+---
+
+## Development Notes
+
+### Deprecated Projects
+**DO NOT USE:**
+- `EnvelopeGenerator.Web` (Razor Pages) — Replaced by unified ReceiverUI
+- PSPDFKit — Removed, use PDF.js + DevExpress instead
+
+### Legacy Projects (VB.NET)
+**DO NOT TOUCH:** `EnvelopeGenerator.Service`, `EnvelopeGenerator.Form`, `EnvelopeGenerator.BBTests`
+
+### Signature Coordinate Evidence
+**File:** `EnvelopeGenerator.Form/frmFieldEditor.vb` (VB.NET)
+
+```vb
+Private Const SIGNATURE_WIDTH As Single = 1.77   ' inches
+Private Const SIGNATURE_HEIGHT As Single = 1.96  ' inches
+
+Sub LoadAnnotation(pElement As Signature, ...)
+    oAnnotation.Left = CSng(pElement.X)    ' Direct INCHES assignment
+    oAnnotation.Top = CSng(pElement.Y)
+End Sub
+```
+
+Proves database uses INCHES natively.
+
+---
+
+## Quick Reference
+
+### When working with coordinates:
+1. **Database ? UI:** INCHES × 72 = PDF Points
+2. **UI ? Display:** Points × scale = Pixels
+3. **iText7 stamping:** Flip Y-axis (top-down ? bottom-up)
+
+### When adding features:
+1. Check `Mistakes History` first
+2. Prefer simplicity over complexity
+3. Use `appsettings.json` for configuration
+4. Keep consistent with existing design (Bootstrap 5 + Blazing Berry)
+5. **Unified frontend:** ReceiverUI serves both Senders and Receivers
+
+### When debugging:
+1. **Coordinates:** Always check unit system (inches/points/pixels)
+2. **Authentication:** Check cookie name/domain/SameSite
+3. **Cache:** Check Redis/SQL connection + key format
+4. **Frontend confusion:** Only use ReceiverUI (Web is deprecated)
+
+---
+
+**Last Updated:** Session 19 (Razor file naming convention + Index route proxy)