AppStd/DocumentService
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1b38d5a729098eff463157e0d4e469730ce7958c
DocumentService/DocumentOperator.API/PHASENPLAN.md
OlgunR 1b38d5a729 Implement attachment detection in ValidatePDF 
Updated PHASENPLAN.md and ROADMAP.md to reflect a complete restructuring of the development plan and added a "Bugfix: Attachment Detection" entry.

Implemented attachment detection in DevExpressPdfProcessor.cs using the new `DetectEmbeddedFiles` method, which scans raw PDF data for the `/EmbeddedFiles` keyword. Updated the `hasAttachments` property to use this method and set `attachmentCount` to `-1` when attachments are detected.

Added a new test, `ValidateAsync_PdfWithoutAttachments_ReturnsNoAttachments`, in DevExpressPdfProcessorTests.cs to verify that PDFs without attachments are correctly identified. Included a note about future testing for PDFs with attachments using ZUGFeRD files.

All related tests are passing (12/12 green).
2026-06-25 16:25:16 +02:00

14 KiB
Raw Blame History

?? DocumentOperator - Phasenplan (Feature-Driven Development)

Stand: 17.01.2025 | Aktuell: Feature 1 - ValidatePDF ? ABGESCHLOSSEN! | Projektdauer: 6 Wochen

?? Übersicht

Woche Features / Concerns Status Fortschritt
W1 Feature 1: ValidatePDF ? Abgeschlossen 100% (Foundation + Application + API + Swagger fertig)
W2 Feature 2: ExtractAttachments ? Geplant 0%
W2 Feature 3: ApplyStamp ? Geplant 0%
W3 Feature 4: EmbedCertificate ? Geplant 0%
W3 Feature 5: ConcatenatePDFs (Async) ? Geplant 0%
W4 Multi-Tenancy (X-API-Key Header) ? Geplant 0%
W5 Health Checks + Polly + Logging ? Geplant 0%
W6 Production Deployment ? Geplant 0%

?? NEUE VORGEHENSWEISE

Was hat sich geändert?

? Feature-by-Feature Development statt Layer-by-Layer

  • Jedes Feature wird KOMPLETT umgesetzt (Domain ? Infrastructure ? Application ? API ? Tests ? Swagger)
  • Feature ist erst "DONE" wenn es im Swagger testbar ist
  • Dann nächstes Feature

? Kleine Schritte (1 Layer pro Step)

  • Nach jedem Step: ROADMAP + PHASENPLAN aktualisieren
  • Commit nach jedem Step
  • Dann weiter

? Multi-Tenancy & Cross-Cutting Concerns später

  • Erst alle synchronen Features (1-4)
  • Dann Multi-Tenancy für ALLE Endpoints
  • Dann Health Checks, Polly, Logging

?? DETAILLIERTER PLAN

WOCHE 1 - Feature 1: ValidatePDF | ? ABGESCHLOSSEN - 100%

Ziel: POST /api/v1/documents/validate Endpoint im Swagger testbar

? Step 1.0: Foundation (ABGESCHLOSSEN)

Dauer: ~2 Tage

Was wurde erstellt:

  • ? Solution Structure (4 Projekte)
  • ? Domain Layer (Exceptions, Enums, Value Objects)
  • ? Infrastructure Layer (DevExpressPdfProcessor.ValidateAsync)
  • ? Tests (DevExpressPdfProcessorTests.cs - 6 Tests)
  • ? Build erfolgreich

? Step 1.1: Application Layer (MediatR Setup + ValidatePDF Feature) - ABGESCHLOSSEN

Dauer: ~4 Stunden

Was wurde erstellt:

  1. MediatR Setup

    • ? Application/DependencyInjection.cs (Service Registration)
    • ? Application/Common/Behaviors/ValidationBehavior.cs (FluentValidation Pipeline)
    • ? Application/Common/Behaviors/LoggingBehavior.cs (Logging Pipeline mit ILogger)

  2. ValidatePDF Feature (Vertical Slice)

    • ? Application/Features/Documents/ValidatePdf/ValidatePdfQuery.cs
    • ? Application/Features/Documents/ValidatePdf/ValidatePdfHandler.cs
    • ? Application/Features/Documents/ValidatePdf/ValidatePdfValidator.cs

  3. DTOs

    • ? Application/Common/DTOs/ValidatePdfRequest.cs
    • ? Application/Common/DTOs/ValidatePdfResponse.cs

  4. Tests

    • ? Tests/Unit/Application/Features/ValidatePdf/ValidatePdfHandlerTests.cs (2 Tests)

Akzeptanzkriterien:

  • ? Build erfolgreich
  • ? Tests grün (Handler Tests: 2/2 passed)
  • ? MediatR Pipeline funktioniert (Validation + Logging)

? Step 1.2: API Layer (Endpoint + Exception Middleware) - ABGESCHLOSSEN

Dauer: ~3 Stunden

Was wurde erstellt:

  1. Exception Middleware

    • ? API/Middleware/ExceptionHandlingMiddleware.cs
    • Exception ? HTTP Status Code Mapping (400, 404, 422, 500)
    • RFC 7807 Problem Details

  2. Minimal API Endpoint

    • ? API/Endpoints/v1/DocumentEndpoints.cs
    • POST /api/v1/documents/validate

  3. Infrastructure DI

    • ? Infrastructure/DependencyInjection.cs
    • IPdfProcessor ? DevExpressPdfProcessor registriert

  4. Program.cs Updates

    • ? Exception Middleware registriert (FIRST in pipeline!)
    • ? DocumentEndpoints registriert
    • ? Application + Infrastructure Services registriert

  5. Integration Tests

    • ? Tests/Integration/API/DocumentEndpointsTests.cs (3 Tests)
    • ? Test: POST_ValidatePdf_ValidPdf_Returns200
    • ? Test: POST_ValidatePdf_InvalidBase64_Returns400
    • ? Test: POST_ValidatePdf_EmptyPdf_Returns400

Akzeptanzkriterien:

  • ? Build erfolgreich
  • ? Integration Tests grün (3/3 passed)
  • ? Endpoint gibt korrekte HTTP Status Codes zurück

? Step 1.3: Swagger Dokumentation - ABGESCHLOSSEN

Dauer: ~1 Stunde

Was wurde erstellt:

  1. Swagger Configuration

    • ? API/Configuration/SwaggerConfiguration.cs
    • ? AddSwaggerDocumentation() Extension Method
    • ? XML Comments aktiviert

  2. XML-Dokumentation aktiviert

    • ? API/DocumentOperator.API.csproj
    • ? <GenerateDocumentationFile>true</GenerateDocumentationFile>

  3. Endpoint Dokumentation

    • ? API/Endpoints/v1/DocumentEndpoints.cs
    • ? XML Comments für ValidatePdf Methode
    • ? Swagger-Annotationen (.WithSummary(), .WithDescription(), .Produces<>())

  4. DTOs Dokumentation

    • ? Application/Common/DTOs/ValidatePdfRequest.cs (XML Comments)
    • ? Application/Common/DTOs/ValidatePdfResponse.cs (XML Comments + FileSizeMB hinzugefügt)

  5. Program.cs Updates

    • ? builder.Services.AddSwaggerDocumentation() statt AddSwaggerGen()
    • ? using DocumentOperator.API.Configuration; hinzugefügt

Akzeptanzkriterien:

  • ? Build erfolgreich
  • ? Alle Tests grün (11/11)
  • ? XML-Dokumentation wird generiert (DocumentOperator.API.xml)
  • ? Swagger UI zeigt Endpoint /api/v1/documents/validate mit Dokumentation
  • ? Request/Response-Schemas sind dokumentiert
  • ? Endpoint ist im Swagger UI testbar

? Feature 1 ABGESCHLOSSEN!

Gesamtdauer: ~1 Tag

Ergebnis:

  • ? POST /api/v1/documents/validate im Swagger testbar
  • ? Unit Tests + Integration Tests grün (11/11)
  • ? Clean Architecture eingehalten
  • ? TDD angewendet
  • ? Swagger-Dokumentation vollständig

WOCHE 2 - Features 2 & 3 | ? Geplant - 0%

Feature 2: ExtractAttachments (Synchron)

Dauer: ~1 Tag Status: ? Pending

Endpoint: POST /api/v1/documents/extract-attachments

Steps:

  • ? Step 2.1: Infrastructure Layer (DevExpressPdfProcessor.ExtractAttachmentsAsync)
  • ? Step 2.2: Application Layer (ExtractAttachmentsCommand + Handler + Validator)
  • ? Step 2.3: API Layer (Endpoint)
  • ? Step 2.4: Swagger Dokumentation

Akzeptanzkriterien:

  • ? Endpoint im Swagger testbar
  • ? Tests grün

Feature 3: ApplyStamp (Synchron)

Dauer: ~1 Tag Status: ? Pending

Endpoint: POST /api/v1/documents/apply-stamp

Steps:

  • ? Step 3.1: Infrastructure Layer (DevExpressPdfProcessor.ApplyStampAsync)
  • ? Step 3.2: Application Layer (ApplyStampCommand + Handler + Validator)
  • ? Step 3.3: API Layer (Endpoint)
  • ? Step 3.4: Swagger Dokumentation

Akzeptanzkriterien:

  • ? Endpoint im Swagger testbar
  • ? Stamp wird korrekt angewendet
  • ? Tests grün

WOCHE 3 - Features 4 & 5 | ? Geplant - 0%

Feature 4: EmbedCertificate (Synchron)

Dauer: ~1 Tag Status: ? Pending

Endpoint: POST /api/v1/documents/embed-certificate

Steps:

  • ? Step 4.1: Infrastructure Layer (DevExpressPdfProcessor.EmbedCertificateAsync)
  • ? Step 4.2: Application Layer (EmbedCertificateCommand + Handler + Validator)
  • ? Step 4.3: API Layer (Endpoint)
  • ? Step 4.4: Swagger Dokumentation

Akzeptanzkriterien:

  • ? Endpoint im Swagger testbar
  • ? Zertifikat wird korrekt eingebettet
  • ? Tests grün

Feature 5: ConcatenatePDFs (Asynchron)

Dauer: ~2 Tage Status: ? Pending

Endpoints:

  • POST /api/v1/documents/concatenate (Async, gibt JobId zurück)
  • GET /api/v1/jobs/{jobId} (Job-Status abfragen)
  • GET /api/v1/jobs/{jobId}/download (Ergebnis herunterladen)

Steps:

  • ? Step 5.1: Infrastructure Layer (In-Memory Queue + Background Worker)
  • ? Step 5.2: Application Layer (SubmitConcatenateJobCommand + GetJobStatusQuery)
  • ? Step 5.3: API Layer (Async Endpoints)
  • ? Step 5.4: Swagger Dokumentation

Akzeptanzkriterien:

  • ? POST /concatenate gibt JobId zurück
  • ? GET /jobs/{jobId} zeigt Status (Pending, Processing, Success, Failed)
  • ? GET /jobs/{jobId}/download gibt PDF zurück
  • ? Background Worker verarbeitet Jobs korrekt
  • ? Tests grün

WOCHE 4 - Multi-Tenancy | ? Geplant - 0%

Ziel: X-API-Key Header für ALLE Endpoints

Was wird gebaut:

  • EF Core + SQLite (Tenant-Datenbank)
  • Redis Cache (API-Key Lookups - optional)
  • TenantResolutionMiddleware (X-API-Key ? Tenant)
  • BCrypt API-Key Hashing
  • Admin API (Tenant CRUD)

Steps:

Step MT.1: EF Core Setup

Dauer: ~3 Stunden

Was wird erstellt:

  • Infrastructure/Data/TenantDbContext.cs
  • Infrastructure/Data/Entities/Tenant.cs
  • Infrastructure/Data/Entities/TenantSettings.cs
  • EF Core Migration (InitialCreate)
  • SQLite Database erstellen

Akzeptanzkriterien:

  • ? Datenbank erstellt
  • ? Tenant-Tabelle existiert
  • ? Build erfolgreich

Step MT.2: TenantResolutionMiddleware

Dauer: ~2 Stunden

Was wird erstellt:

  • API/Middleware/TenantResolutionMiddleware.cs
  • Application/Common/Interfaces/ITenantContext.cs
  • Infrastructure/Services/TenantContext.cs

Akzeptanzkriterien:

  • ? X-API-Key Header wird gelesen
  • ? Tenant aus DB geladen
  • ? ITenantContext im Request Scope verfügbar
  • ? Ungültiger API-Key ? HTTP 401

Step MT.3: Redis Cache Integration (Optional)

Dauer: ~1 Stunde

Was wird erstellt:

  • Redis Cache für API-Key Lookups
  • TTL: 1 Stunde

Akzeptanzkriterien:

  • ? API-Key Lookup cached (weniger DB-Calls)
  • ? Cache Invalidation funktioniert

Step MT.4: Admin API (Tenant Management)

Dauer: ~2 Stunden

Was wird erstellt:

  • POST /api/v1/admin/tenants (Create Tenant)
  • PUT /api/v1/admin/tenants/{id}/rotate-key (API-Key rotieren)
  • PATCH /api/v1/admin/tenants/{id}/deactivate (Tenant deaktivieren)
  • GET /api/v1/admin/tenants (Liste aller Tenants)

Akzeptanzkriterien:

  • ? Endpoints im Swagger testbar
  • ? API-Key wird gehashed (BCrypt)
  • ? Tests grün

Step MT.5: Alle Endpoints mit X-API-Key absichern

Dauer: ~1 Stunde

Was wird geändert:

  • Alle Feature-Endpoints bekommen X-API-Key Header Requirement
  • Swagger zeigt API-Key Security Scheme

Akzeptanzkriterien:

  • ? Alle Endpoints erfordern X-API-Key Header
  • ? Swagger zeigt Security Scheme
  • ? Tests aktualisiert (mit API-Key)

WOCHE 5 - Health Checks + Polly + Logging | ? Geplant - 0%

Health Checks

Dauer: ~2 Stunden

Was wird gebaut:

  • /health Endpoint (Liveness/Readiness Probes)
  • DevExpressPdfHealthCheck (Smoke Test)
  • Database Health Check (SQLite)
  • Redis Health Check (optional)

Akzeptanzkriterien:

  • ? /health gibt HTTP 200 wenn alles OK
  • ? /health gibt HTTP 503 wenn DevExpress nicht funktioniert

Polly Resilience

Dauer: ~3 Stunden

Was wird gebaut:

  • Retry Policy (3x mit Exponential Backoff)
  • Circuit Breaker (nach 5 Fehlern 30s öffnen)
  • Timeout Policy (30s max)

Akzeptanzkriterien:

  • ? DevExpress Calls werden mit Polly gewickelt
  • ? Retry funktioniert bei Transient Errors
  • ? Circuit Breaker öffnet bei vielen Fehlern

Logging & Monitoring

Dauer: ~3 Stunden

Was wird gebaut:

  • CorrelationIdMiddleware (X-Correlation-ID Header)
  • Seq Sink (Log-Browsing UI)
  • File Logging (Production)
  • LoggingBehavior erweitert (Performance-Tracking)

Akzeptanzkriterien:

  • ? Correlation IDs in allen Logs
  • ? Seq UI zeigt Logs (Development)
  • ? File Logging funktioniert (Production)

WOCHE 6 - Production Deployment | ? Geplant - 0%

Ziel: Service ist produktionsreif

Was wird gebaut:

  • appsettings.Production.json (Production Settings)
  • IIS Web.config (Kestrel Settings)
  • SSL/TLS Zertifikat konfigurieren
  • Deployment-Skript (PowerShell)

Steps:

Deployment Vorbereitung

Dauer: ~4 Stunden

Was wird erstellt:

  • appsettings.Production.json (Prod-Settings)
  • Web.config (IIS Integration)
  • PowerShell Deploy-Skript
  • Dokumentation (README.md)

Akzeptanzkriterien:

  • ? Build in Release Mode erfolgreich
  • ? IIS Deployment funktioniert
  • ? HTTPS funktioniert

Production Testing

Dauer: ~4 Stunden

Was wird getestet:

  • Alle Endpoints im Production-Modus
  • Health Checks
  • Multi-Tenancy
  • Performance (Load Testing)

Akzeptanzkriterien:

  • ? Alle Features funktionieren in Production
  • ? Health Checks grün
  • ? Performance OK (< 1s Response Time)

?? FORTSCHRITTS-TRACKING

Gesamt-Fortschritt

Kategorie Status Fortschritt
Foundation ? Abgeschlossen 100%
Feature 1 ? Abgeschlossen 100%
Feature 2-5 ? Pending 0%
Multi-Tenancy ? Pending 0%
Cross-Cutting ? Pending 0%
Production ? Pending 0%

?? NEXT STEPS

Nächstes Feature

Feature 2: ExtractAttachments - NEXT

  1. ? Step 2.1: Infrastructure Layer (DevExpressPdfProcessor.ExtractAttachmentsAsync)
  2. ? Step 2.2: Application Layer (ExtractAttachmentsCommand + Handler + Validator + DTOs)
  3. ? Step 2.3: API Layer (Endpoint + Integration Tests)
  4. ? Step 2.4: Swagger Dokumentation

Erwarteter Zeitaufwand: ~1 Tag

Akzeptanzkriterien:

  • ? POST /api/v1/documents/extract-attachments im Swagger testbar
  • ? Alle Tests grün
  • ? Clean Architecture eingehalten

?? UPDATE LOG

Date Feature/Step Changes
2024-XX-XX Foundation Project setup, dependencies, folder structure
2024-XX-XX Domain Layer Exceptions, Enums, Value Objects
17.01.2025 Infrastructure DevExpressPdfProcessor.ValidateAsync implementiert
17.01.2025 Tests DevExpressPdfProcessorTests.cs erstellt (6 Tests)
17.01.2025 PHASENPLAN ?? Komplett umstrukturiert (Feature-basiert + Datum korrigiert 23.06.2026 ? 17.01.2025)
17.01.2025 Feature 1 - Step 1.1 ? ABGESCHLOSSEN - Application Layer (MediatR, Behaviors, ValidatePDF Feature, DTOs, Tests - 2/2 grün)
17.01.2025 Feature 1 - Step 1.2 ? ABGESCHLOSSEN - API Layer (ExceptionMiddleware, Endpoint, Program.cs, Integration Tests - 3/3 grün)
17.01.2025 Feature 1 - Step 1.3 ? ABGESCHLOSSEN - Swagger Dokumentation (SwaggerConfiguration, XML Comments, Endpoint/DTO-Dokumentation - 11/11 Tests grün)
17.01.2025 Feature 1 ? KOMPLETT ABGESCHLOSSEN - ValidatePDF Feature testbar im Swagger UI!
17.01.2025 Bugfix: Attachment Detection ? IMPLEMENTIERT - ValidatePDF erkennt jetzt Attachments (ZUGFeRD-PDFs) korrekt - 12/12 Tests grün

END OF PHASENPLAN

This document is a living document and will be updated after each completed step.

Reference in New Issue View Git Blame Copy Permalink