docs: Add AGENTS.md architecture guidance for AI agents

Comprehensive architecture documentation including: - Clean Architecture with Controller-based API (NOT Minimal API) - Vertical slice architecture pattern - Exception-based error handling (no Result<T>) - Feature-driven development approach - Primary constructor coding standards - Git commit guidelines - Swiss QR Bill backward compatibility decisions Key decisions documented: - Windows-only targeting (no Linux support needed) - Support BOTH multipart/form-data AND Base64 JSON - Separate endpoints for Combined Address (K-Type) legacy support - Multi-tenancy deferred until after all sync features complete
2026-07-07 19:00:12 +02:00
parent 077eb1e017
commit f8690b9417
1 changed files with 638 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,638 @@
 # AGENTS.md
 Agent guidance for DocumentOperator service. Read this before working on the codebase.
 ---
 ## ⚠️ CRITICAL: Architecture Decision Change
 **Previous developer used Minimal API** (`DocumentEndpoints.cs`), but this is **WRONG**.
 **YOU MUST use Controller-based approach** as specified in `CONTROLLER_ENDPOINTS.md`.
 ### Key Differences
 | Previous Approach (WRONG) | Required Approach (CORRECT) |
 |---------------------------|------------------------------|
 | Minimal API (`DocumentEndpoints.cs`) | **Controllers** (`PdfValidationController`, etc.) |
 | Only Base64 JSON | **Both multipart/form-data AND Base64 JSON** |
 | `/api/v1/documents/validate` | **`/api/pdf/validation/validate`** |
 **Do NOT follow ROADMAP.md's "Minimal API" guidance.** It conflicts with the requirements.
 ### Migration Required
 **Existing code that needs replacement:**
 - `DocumentOperator.API/Endpoints/v1/DocumentEndpoints.cs` → Delete, replace with Controllers
 - `Program.cs` line 72: `app.MapDocumentEndpoints()` → Replace with `app.MapControllers()`
 - `Program.cs` line 44: Add `builder.Services.AddControllers()`
 - All DTOs → Support **BOTH** `IFormFile` (multipart) AND `Base64String` (JSON)
 **Dual Input Support Required:**
 - Controllers must accept **BOTH** file upload (multipart/form-data) and Base64 JSON
 - Each endpoint should have overloads or flexible parameter binding
 - Preserve existing Base64 functionality while adding file upload support
 ---
 ## Architecture & Development Approach
 **Clean Architecture with Controller-Based API:**
 - 4 layers: API → Application → Infrastructure → Domain
 - Domain has **ZERO** external dependencies (only standard .NET)
 - Feature-driven development: complete one feature end-to-end before starting the next
 - Feature = Domain + Infrastructure + Application + **Controller** + Tests + Swagger (all layers)
 **Dependency flow (enforced):**
 ```
 API → Application → Domain
 API → Infrastructure → Application
 Infrastructure → Application (for interfaces only)
 Domain → NOTHING
 ```
 **Vertical Slice structure** (NOT horizontal layers):
 ```
 Features/Documents/
 ├── ValidatePdf/
 │   ├── ValidatePdfQuery.cs          (request)
 │   ├── ValidatePdfHandler.cs        (logic)
 │   └── ValidatePdfValidator.cs      (validation)
 └── ExtractSwissQrCode/
    ├── ExtractSwissQrCodeQuery.cs
    ├── ExtractSwissQrCodeHandler.cs
    └── ExtractSwissQrCodeValidator.cs
 ```
 All files for a feature live together. Do NOT create separate Commands/, Handlers/, Validators/ folders.
 ---
 ## 🏗️ Architecture Principles
 ### Clean Architecture (Pragmatic)
 **4 Layers with strict dependency rules:**
 - API → Application → Domain
 - Infrastructure → Application (interfaces only)
 - Domain → NOTHING (zero external dependencies)
 **Key Principles:**
 - ✅ Testability (Application layer mocks Infrastructure services)
 - ✅ Replaceability (swap DevExpress without touching Application)
 - ✅ Separation of Concerns
 - ❌ NO overengineering (only what we need, YAGNI principle)
 - ❌ NO speculative abstractions (wait for 2nd use case)
 ### CQRS with MediatR
 **Why MediatR:**
 - 1 Command/Query = 1 Handler = 1 Responsibility
 - Isolated, testable handlers
 - Pipeline Behaviors (Validation, Logging) run centrally
 - Avoids bloated services with 20+ methods
 **Pattern:**
 - **Command:** Modifies data (ApplyStamp, EmbedCertificate)
 - **Query:** Reads data (ValidatePdf returns metadata only)
 **Pipeline:** ValidationBehavior → LoggingBehavior → Handler
 ### Vertical Slice Architecture
 **NOT Horizontal** (Commands/, Handlers/, Validators/ folders)  
 **YES Vertical** (all files for one feature together)
 **Benefits:**
 - Related code stays together (high cohesion)
 - Easier to find ("Where's ValidatePdf?" → one folder!)
 - Easier to modify (all files in same folder)
 - Fewer merge conflicts in teams
 ### Exception-Based Error Handling
 **NO Result<T> pattern library**
 **Flow:**
 1. FluentValidation (DTO level) → ValidationException → 400
 2. Domain validation → DomainValidationException → 400
 3. Business logic → DomainException → 400/404
 4. Infrastructure → PdfProcessingException → 500
 **Middleware:** Central exception handler maps exceptions to HTTP status codes
 **Why exceptions:**
 - Simpler code (no `if (result.IsSuccess)` everywhere)
 - Less boilerplate (no Result<T> wrapping)
 - Standard .NET exception flow
 - Centralized error handling (one place to maintain)
 ### Feature-Driven Development
 **Feature-Driven (NOT Layer-by-Layer):**
 - Complete one feature end-to-end before starting next
 - Feature = Domain + Infrastructure + Application + API + Tests + Swagger
 - Feature is DONE when testable in Swagger UI
 **Why:**
 - Faster value delivery (Feature 1 done in ~1 day)
 - Clear definition of done (Swagger testable)
 - Less complexity (not all layers in parallel)
 - Better learning (pattern repeats)
 **Alternative rejected:** Complete all Domain → all Infrastructure → all Application → all API  
 **Problem:** Too much speculative code without visible results
 ### Test-Driven Development (TDD)
 **Flow:** Red → Green → Refactor
 **Test Pyramid:**
 - **Unit Tests (many):** Value Objects, Handlers, Services
 - **Integration Tests (some):** Endpoints, MediatR Pipeline
 - **E2E Tests (few/none):** API is already top-level
 **Why TDD:**
 - Tests as documentation
 - Tests as safety net for refactoring
 - Better design (testable = good code)
 - No forgotten tests (test comes FIRST)
 ### Cross-Cutting Concerns Timing
 **Multi-Tenancy Implementation Deferred**
 **Decision:** Implement multi-tenancy (X-API-Key header, tenant database, Redis cache) AFTER all synchronous PDF operation features are complete.
 **Why:**
 - Multi-tenancy affects ALL endpoints
 - Better to implement once for all features (avoid repetition)
 - Easier to test features first without tenancy, then add tenancy layer
 - Cleaner separation: Features first, then cross-cutting concerns
 **Impact on current architecture:**
 - ❌ NO Entity Framework yet (tenant database comes with multi-tenancy)
 - ❌ NO Redis yet (API key caching comes with multi-tenancy)
 - ❌ NO X-API-Key authentication yet (comes with multi-tenancy)
 - ✅ All features currently work without authentication
 **When to implement:**
 After completing all Phase 1-3 controllers (PdfValidation, PdfAttachment, PdfOperations, PdfRender, PdfConversion), then add multi-tenancy to ALL endpoints in one refactoring phase.
 ---
 ## Build, Test, Run
 **Build:**
 ```powershell
 dotnet build
 ```
 **Run tests (19 tests as of Feature 2):**
 ```powershell
 dotnet test
 ```
 **Run API (Development):**
 ```powershell
 dotnet run --project DocumentOperator.API
 ```
 Swagger UI: `https://localhost:<port>/swagger`
 **Target framework:** .NET 8.0  
 **SDK required:** 8.0.412 or later (repo has 8.0.412–10.0.203 available)
 ---
 ## Key Libraries & Their Roles
 | Library | Purpose | Where Used |
 |---------|---------|------------|
 | **DevExpress.Document.Processor** (26.1.3) | PDF operations (validation, QR extraction, attachments) | Infrastructure layer only |
 | **Codecrete.SwissQRBill.Generator** (3.4.0) | Swiss QR Bill parsing (Standard 2.0) | Infrastructure.Services.QrCodeProcessing |
 | **ZXing.Net.Bindings.Windows.Compatibility** (0.16.14) | QR code image decoding | Infrastructure.Services.QrCodeProcessing |
 | **MediatR** (14.1.0) | CQRS: 1 handler per feature | Application layer |
 | **FluentValidation** (12.1.1) | Request validation (runs via ValidationBehavior before handlers) | Application layer |
 | **Serilog.AspNetCore** (10.0.0) | Structured logging | API layer |
 **Critical:** DevExpress requires a license. All PDF operations use `DevExpress.Pdf.PdfDocumentProcessor`.
 ---
 ## Exception Handling Strategy
 **No Result<T> pattern.** Use exceptions + central middleware.
 **Flow:**
 1. FluentValidation validates request DTOs → throws `ValidationException` → HTTP 400
 2. Domain validation in Value Objects → throws `DomainValidationException` → HTTP 400
 3. Business logic errors → throws `DomainException` subtypes → HTTP 400/404/500
 4. Infrastructure errors (e.g., PDF parsing) → throws `PdfProcessingException` → HTTP 500
 **Middleware maps exceptions to HTTP status codes** (`ExceptionHandlingMiddleware.cs`).
 Do NOT add `if (result.IsSuccess)` checks. Throw exceptions for errors. The middleware handles the rest.
 ---
 ## Required Controllers & Endpoints
 **See `CONTROLLER_ENDPOINTS.md` for complete specification.**
 ### Priority Order
 **Phase 1 (PRIORITY):**
 1. `PdfValidationController` – 2 endpoints
   - `POST /api/pdf/validation/validate` (Basic PDF validation)
   - `POST /api/pdf/validation/validate-pdfa` (PDF/A conformance)
 2. `PdfAttachmentController` – 2 endpoints
   - `POST /api/pdf/attachments/check` (Attachment detection)
   - `POST /api/pdf/attachments/extract` (Extract attachments)
 3. `PdfOperationsController` – Merge endpoint
   - `POST /api/pdf/operations/merge` (Merge multiple PDFs)
 **Phase 2:**
 4. `PdfOperationsController` – Stamp & Annotate
 5. `PdfRenderController` – Preview
 **Phase 3:**
 6. `PdfConversionController` – PDF ↔ PDF/A conversion
 ### Current Status
 | Controller | Status | Tests |
 |-----------|--------|-------|
 | **PdfValidationController** | ⏳ Pending | 0 |
 | **PdfAttachmentController** | ⏳ Pending | 0 |
 | **PdfOperationsController** | ⏳ Pending | 0 |
 | **PdfRenderController** | ⏳ Pending | 0 |
 | **PdfConversionController** | ⏳ Pending | 0 |
 **Legacy code exists** (`DocumentEndpoints.cs` with Minimal API + Base64 JSON), but **must be replaced** with Controllers + multipart/form-data.
 ---
 ## Adding a New Feature
 **Required steps (follow CONTROLLER_ENDPOINTS.md):**
 1. **Domain:** Value Objects, Exceptions (if needed)
 2. **Infrastructure:** Service interface + DevExpress implementation + unit tests
 3. **Application:** Query/Command + Handler + FluentValidator + DTOs + unit tests
 4. **API:** **Controller** + actions + integration tests
 5. **Swagger:** XML comments on controller actions + DTOs
 **Example (PdfValidationController):**
 ```
 Step 1: Application/Features/Documents/ValidatePdf/
  - ValidatePdfCommand.cs (record)
  - ValidatePdfHandler.cs (IRequestHandler)
  - ValidatePdfValidator.cs (AbstractValidator)
 Step 2: API/Controllers/PdfValidationController.cs
  - [HttpPost("validate")] action
  - Accepts IFormFile (multipart/form-data)
  - Returns ValidatePdfResponse
 Step 3: XML comments + [ProducesResponseType] attributes
 ```
 **CRITICAL: Support BOTH multipart/form-data AND Base64 JSON for all file-based endpoints.**
 **Input Flexibility:**
 - Primary: `IFormFile` (multipart/form-data) - for direct file uploads
 - Secondary: `Base64String` (application/json) - for API clients that can't send multipart
 Do NOT skip steps. Each feature is done when it's **testable in Swagger UI with both input methods**.
 ---
 ## Test Data
 **Embedded test PDFs:**
 - `TestData/Pdfs/valid.pdf` (simple PDF for validation)
 - `TestData/Pdfs/pdfWithSwissQRCode.pdf` (Swiss QR Code on last page)
 - `TestData/Pdfs/pdfWithMoreThanOneAttachment.pdf` (6 attachments)
 **All test PDFs are EmbeddedResource.** Access via:
 ```csharp
 var stream = Assembly.GetExecutingAssembly()
    .GetManifestResourceStream("DocumentOperator.Tests.TestData.Pdfs.valid.pdf");
 ```
 **Do NOT commit new binary files** without marking them as `<EmbeddedResource>`.
 ---
 ## Swiss QR Code Feature (Feature 2)
 **Swiss QR Bill Standard 2.0** requires:
 - QR code is on the **last page** of the PDF (not first!)
 - Use `DevExpress.Pdf.PdfDocumentProcessor` to render last page as image
 - Use `ZXing` to decode QR code from image
 - Use `Codecrete.SwissQRBill.Generator` to parse Swiss QR Bill payload
 **Known quirks:**
 - PDF must be rendered at **300 DPI** for reliable QR detection
 - Alternative procedure parameters (AV1, AV2) are split by newline, not semicolon
 ---
 ## MediatR Pipeline Behaviors
 **Two behaviors run for EVERY request:**
 1. **ValidationBehavior** (runs first): Executes all `IValidator<TRequest>` and throws `ValidationException` if invalid
 2. **LoggingBehavior** (runs second): Logs request name + execution time
 **Registered in:** `Application/DependencyInjection.cs`
 Do NOT manually call validators in handlers. The pipeline does it.
 ---
 ## Controller Pattern (CORRECT Approach)
 **Controllers must support BOTH file upload and Base64 input.**
 ### Option 1: Separate Endpoints (Recommended)
 ```csharp
 [ApiController]
 [Route("api/pdf/validation")]
 public class PdfValidationController : ControllerBase
 {
    private readonly IMediator _mediator;
    public PdfValidationController(IMediator mediator)
    {
        _mediator = mediator;
    }
    /// <summary>
    /// Validates a PDF document (multipart/form-data)
    /// </summary>
    [HttpPost("validate")]
    [Consumes("multipart/form-data")]
    [ProducesResponseType(typeof(ValidatePdfResponse), 200)]
    [ProducesResponseType(typeof(ProblemDetails), 400)]
    public async Task<IActionResult> ValidateFromFile(IFormFile file, CancellationToken ct)
    {
        using var ms = new MemoryStream();
        await file.CopyToAsync(ms, ct);
        byte[] pdfBytes = ms.ToArray();
        var command = new ValidatePdfCommand(pdfBytes);
        var result = await _mediator.Send(command, ct);
        return Ok(result);
    }
    /// <summary>
    /// Validates a PDF document (Base64 JSON)
    /// </summary>
    [HttpPost("validate")]
    [Consumes("application/json")]
    [ProducesResponseType(typeof(ValidatePdfResponse), 200)]
    [ProducesResponseType(typeof(ProblemDetails), 400)]
    public async Task<IActionResult> ValidateFromBase64(
        [FromBody] ValidatePdfRequest request, 
        CancellationToken ct)
    {
        var query = new ValidatePdfQuery(Base64String.Create(request.Base64Pdf));
        var result = await _mediator.Send(query, ct);
        return Ok(result);
    }
 }
 ```
 ### Option 2: Single Endpoint with Model Binding
 ```csharp
 public class PdfInputModel
 {
    public IFormFile? File { get; set; }
    public string? Base64Pdf { get; set; }
 }
 [HttpPost("validate")]
 public async Task<IActionResult> Validate([FromForm] PdfInputModel input, CancellationToken ct)
 {
    byte[] pdfBytes = input.File != null 
        ? await GetBytesFromFile(input.File)
        : Base64String.Create(input.Base64Pdf!).ToByteArray();
    // Process...
 }
 ```
 **Use Controllers, NOT Minimal API endpoints.**
 ---
 ## Configuration
 **appsettings.json sections:**
 - `DocumentOperatorSettings` (future: file size limits, temp paths)
 - `RedisSettings` (future: multi-tenancy caching)
 - `ApiKeySettings` (future: authentication)
 **Currently:** All features work without authentication. Multi-tenancy is deferred until after all sync features are complete.
 ---
 ## Coding Standards
 ### Primary Constructors
 **ALWAYS use primary constructors** (C# 12 feature) unless there's a technical limitation.
 **✅ Correct:**
 ```csharp
 public class PdfValidationController(IMediator mediator, ILogger<PdfValidationController> logger) : ControllerBase
 {
    // Use parameters directly, no field declarations needed
    public async Task<IActionResult> Validate(...)
    {
        await mediator.Send(...);
    }
 }
 ```
 **❌ Wrong:**
 ```csharp
 public class PdfValidationController : ControllerBase
 {
    private readonly IMediator _mediator;
    private readonly ILogger<PdfValidationController> _logger;
    public PdfValidationController(IMediator mediator, ILogger<PdfValidationController> logger)
    {
        _mediator = mediator;
        _logger = logger;
    }
 }
 ```
 ### Controller Responsibilities
 **Controllers should be thin.** Do NOT add mapping logic.
 **✅ Correct:**
 ```csharp
 public async Task<IActionResult> Validate([FromBody] ValidatePdfRequest request, CancellationToken ct)
 {
    // Direct pass-through to MediatR
    var result = await mediator.Send(request, ct);
    return Ok(result);
 }
 ```
 **❌ Wrong:**
 ```csharp
 public async Task<IActionResult> Validate([FromBody] ValidatePdfRequest request, CancellationToken ct)
 {
    // Manual mapping (WRONG!)
    var command = new ValidatePdfCommand(request.Base64Pdf);
    var metadata = await mediator.Send(command, ct);
    var response = new ValidatePdfResponse(metadata.PageCount, ...);
    return Ok(response);
 }
 ```
 **If mapping is absolutely necessary:** Use AutoMapper.
 ### Request DTOs - Flexible Input
 **Support BOTH `byte[]` and `Base64String` in requests.**
 ```csharp
 public record ValidatePdfRequest
 {
    public byte[]? PdfBytes { get; init; }
    public string? Base64Pdf { get; init; }
 }
 ```
 **FluentValidation:** Ensure exactly ONE is provided:
 ```csharp
 public class ValidatePdfRequestValidator : AbstractValidator<ValidatePdfRequest>
 {
    public ValidatePdfRequestValidator()
    {
        RuleFor(x => x)
            .Must(x => (x.PdfBytes != null && x.PdfBytes.Length > 0) ^ 
                       (!string.IsNullOrWhiteSpace(x.Base64Pdf)))
            .WithMessage("Either PdfBytes or Base64Pdf must be provided, but not both");
    }
 }
 ```
 **Handler:** Use `byte[]` if available, otherwise convert Base64:
 ```csharp
 public async Task<PdfMetadata> Handle(ValidatePdfRequest request, CancellationToken ct)
 {
    byte[] pdfBytes = request.PdfBytes ?? Convert.FromBase64String(request.Base64Pdf!);
    return await _processor.ValidateAsync(pdfBytes);
 }
 ```
 ### No Unnecessary Value Objects
 **Do NOT create value objects for simple types** (e.g., Base64String).
 **❌ Wrong:** Creating `Base64String` value object just to wrap `string`
 **✅ Correct:** Use `string` directly + extension methods if needed
 **Why:** 
 - Performance overhead (validation runs twice: once in value object, once in FluentValidation)
 - Unnecessary abstraction (YAGNI principle)
 - `Convert.FromBase64String()` already validates format
 ### Exception Handling in Controllers
 **Let FormatException bubble up naturally.** ExceptionHandlingMiddleware will catch it.
 ```csharp
 // Handler
 byte[] pdfBytes = request.PdfBytes ?? Convert.FromBase64String(request.Base64Pdf!);
 // If Base64 is invalid, FormatException → Middleware → 400 Bad Request
 ```
 **Middleware handles:**
 - `FormatException` → 400 Bad Request
 - `ValidationException` → 400 Bad Request
 - `DomainException` → 400/404
 - `PdfProcessingException` → 500
 ---
 ## Git Commit Guidelines
 ### ⚠️ CRITICAL: Never Commit Without Approval
 **NEVER run `git commit` without explicit user approval.**
 ### Systematic Commits
 **Do NOT commit everything in one giant commit.**
 **✅ Correct approach:**
 1. Complete one logical change (e.g., "Add PdfValidationController")
 2. Stage only related files: `git add <specific-files>`
 3. Ask user: "Ready to commit 'Add PdfValidationController'?"
 4. After approval: `git commit -m "Add PdfValidationController with dual input support"`
 5. Repeat for next logical change
 **❌ Wrong approach:**
 ```bash
 git add -A
 git commit -m "Migrate everything to controllers, update tests, add AGENTS.md, delete ROADMAP.md"
 # This is TOO MUCH in one commit!
 ```
 **Good commit messages:**
 - `feat: Add PdfValidationController with multipart/form-data support`
 - `refactor: Replace Base64String value object with direct string usage`
 - `test: Add integration tests for PdfValidationController`
 - `docs: Add AGENTS.md with architecture guidance`
 - `chore: Delete deprecated ROADMAP.md`
 **Commit size guideline:** 1-5 files per commit, one logical change
 ---
 ## What NOT to Do
 - ❌ Do NOT create horizontal folders (Commands/, Handlers/, Validators/)
 - ❌ Do NOT add Entity Framework until multi-tenancy phase
 - ❌ Do NOT use Minimal API endpoints (use Controllers instead)
 - ❌ Do NOT support only ONE input type (must support BOTH multipart AND Base64)
 - ❌ Do NOT use Result<T> pattern (use exceptions)
 - ❌ Do NOT skip tests (TDD: write test first, then implementation)
 - ❌ Do NOT add dependencies to Domain layer (keep it clean!)
 - ❌ Do NOT commit without user approval
 - ❌ Do NOT use old-style constructors (use primary constructors)
 - ❌ Do NOT add mapping logic in controllers (keep them thin)
 - ❌ Do NOT create unnecessary value objects (YAGNI principle)
 ---
 ## Debugging Tips
 **DevExpress PDF errors:**
 - Check if file is actually a valid PDF (magic bytes: `%PDF-`)
 - DevExpress throws generic exceptions; wrap in try-catch and add context
 **Swiss QR Code not found:**
 - Verify QR is on **last page** (not first)
 - Check DPI setting (300 DPI required, see ROADMAP.md Feature 2)
 - Use `ZXing` with `TryHarder` hint enabled
 **Attachment count wrong:**
 - Search entire PDF stream, not just first 1000 chars (see ROADMAP.md fix log 17.01.2025)
 - Count `/EmbeddedFiles` object references correctly (not divided by 2)
 ---
 ## References
 - **CONTROLLER_ENDPOINTS.md** – **PRIMARY SOURCE** for API specification (all planned endpoints)
 - **REQUIRED_FEATURES.md** – Business requirements (what PDF operations are needed and why)
 - **ROADMAP.md** – Feature-by-feature implementation plan (1101 lines, detailed) **NOTE: Uses Minimal API, which is incorrect. Follow CONTROLLER_ENDPOINTS.md instead.**
 - **DevExpress Docs** – https://docs.devexpress.com/OfficeFileAPI/
 - **Swiss QR Bill Standard** – https://www.ferd-net.de/ (ZUGFeRD/XRechnung context)
 **When implementing endpoints:** Follow CONTROLLER_ENDPOINTS.md, NOT ROADMAP.md's Minimal API approach.