AppStd/DocumentService
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
18e956c2cfda72593ad57d185bb59477ddb8a582
DocumentService/DocumentOperator.API/PHASENPLAN.md
OlgunR 18e956c2cf Enhance PDF attachment detection and counting 
Refactored `DevExpressPdfProcessor` to improve attachment detection:
- Changed `DetectEmbeddedFiles` return type to a tuple for better
  handling of attachment presence and count.
- Enhanced logic to parse `/Names` arrays and count object references
  for accurate attachment detection.
- Implemented robust search for `/EmbeddedFiles` to handle multiple
  occurrences and ensure proper context validation.

Updated PHASENPLAN.md and ROADMAP.md to reflect these changes, including
the addition of fixes for attachment detection and counting logic.

Added new tests in `DevExpressPdfProcessorTests`:
- Verified detection of multiple attachments and accurate counts.
- Ensured no crashes when processing PDFs with `/EmbeddedFiles`.

Included a new test resource (`pdfWithMoreThanOneAttachment.pdf`) for
validating multiple attachment scenarios.
2026-06-25 17:17:32 +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 Fix: Attachment Detection (Multiple Attachments) ? KORRIGIERT - ValidatePDF erkennt jetzt auch PDFs mit mehreren Attachments korrekt (globale Suche statt 1000-Zeichen-Limit) - 13/13 Tests grün
17.01.2025 Fix: Attachment Count (6 Attachments) ? KORRIGIERT - AttachmentCount wird jetzt korrekt gezählt (objectCount statt objectCount/2). PDFs mit 6 Attachments werden korrekt erkannt - 13/13 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