AppStd/DocumentService
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
586fd4a20783abcd88d1ed280fbe43b3c9a35c6f
DocumentService/DocumentOperator.API/PHASENPLAN.md
OlgunR 47cba50d0f Add ExtractSwissQrCode feature and update feature order 
Updated PHASENPLAN.md and ROADMAP.md to reflect the new
feature order, making "ExtractSwissQrCode" Feature 2 and
renumbering previous Features 2-5 to 3-6. Added detailed
steps, endpoints, and acceptance criteria for the new
feature.

Implemented `ISwissQrCodeProcessor` interface with
`DevExpressSwissQrCodeProcessor` for extracting and parsing
Swiss QR Codes using DevExpress and Codecrete libraries.
Registered the new service in DependencyInjection.cs.

Introduced `SwissQrCodeData` value object and
`SwissQrCodeNotFoundException` for domain modeling and
error handling. Updated project dependencies to include
libraries for QR code processing.

Adjusted existing feature descriptions and steps to align
with the new feature order.
2026-06-26 08:39:44 +02:00

16 KiB
Raw Blame History

?? DocumentOperator - Phasenplan (Feature-Driven Development)

Stand: 17.01.2025 | Aktuell: Feature 2 - ExtractSwissQrCode ? IN PROGRESS | Projektdauer: 6 Wochen

?? Übersicht

Woche Features / Concerns Status Fortschritt
W1 Feature 1: ValidatePDF ? Abgeschlossen 100% (Foundation + Application + API + Swagger fertig)
W1-W2 Feature 2: ExtractSwissQrCode ? In Progress 0% (Gerade gestartet!)
W2 Feature 3: ExtractAttachments ? Geplant 0%
W2 Feature 4: ApplyStamp ? Geplant 0%
W3 Feature 5: EmbedCertificate ? Geplant 0%
W3 Feature 6: 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 1-2 - Feature 2: ExtractSwissQrCode | ? In Progress - 0%

Dauer: ~1-2 Tage Status: ? In Progress (gerade gestartet!)

Endpoint: POST /api/v1/documents/extract-swiss-qr-code

Was wird gebaut:

  • Client sendet Referenzen (Array) + PDF (Base64)
  • API extrahiert Swiss QR Code von letzter Seite
  • API gibt Referenzen + alle QR Code Felder zurück (Swiss QR Bill Standard 2.0)

Technologie:

  • DevExpress PDF Document API (PDF-Zugriff, letzte Seite)
  • Codecrete.SwissQRBill.Generator (Swiss QR Code Parsing - Standard 2.0)

Steps:

  • ?? Step 2.1: Domain Layer (SwissQrCodeData Value Object)
  • ?? Step 2.2: Infrastructure Layer (IQrCodeProcessor + DevExpressSwissQrCodeProcessor + Codecrete Integration)
  • ?? Step 2.3: Application Layer (ExtractSwissQrCodeQuery + Handler + Validator)
  • ?? Step 2.4: API Layer (Endpoint + Integration Tests)
  • ?? Step 2.5: Swagger Dokumentation

Akzeptanzkriterien:

  • ? QR Code wird von letzter Seite extrahiert
  • ? Alle Swiss QR Bill Felder werden geparst (Standard 2.0)
  • ? Referenzen werden durchgeschliffen (Echo)
  • ? Fehler wenn kein QR Code gefunden
  • ? Swagger-testbar
  • ? Tests grün

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

Feature 3: ExtractAttachments (Synchron)

Dauer: ~1 Tag Status: ? Pending

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

Steps:

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

Akzeptanzkriterien:

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

Feature 4: ApplyStamp (Synchron)

Dauer: ~1 Tag Status: ? Pending

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

Steps:

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

Akzeptanzkriterien:

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

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

Feature 5: EmbedCertificate (Synchron)

Dauer: ~1 Tag Status: ? Pending

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

Steps:

  • ? Step 5.1: Infrastructure Layer (DevExpressPdfProcessor.EmbedCertificateAsync)
  • ? Step 5.2: Application Layer (EmbedCertificateCommand + Handler + Validator)
  • ? Step 5.3: API Layer (Endpoint)
  • ? Step 5.4: Swagger Dokumentation

Akzeptanzkriterien:

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

Feature 6: 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 6.1: Infrastructure Layer (In-Memory Queue + Background Worker)
  • ? Step 6.2: Application Layer (SubmitConcatenateJobCommand + GetJobStatusQuery)
  • ? Step 6.3: API Layer (Async Endpoints)
  • ? Step 6.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: ExtractSwissQrCode - IN PROGRESS

  1. ?? Step 2.1: Domain Layer (SwissQrCodeData Value Object)
  2. ?? Step 2.2: Infrastructure Layer (IQrCodeProcessor + DevExpressSwissQrCodeProcessor + Codecrete Integration)
  3. ?? Step 2.3: Application Layer (ExtractSwissQrCodeQuery + Handler + Validator + DTOs)
  4. ?? Step 2.4: API Layer (Endpoint + Integration Tests)
  5. ?? Step 2.5: Swagger Dokumentation

Erwarteter Zeitaufwand: ~1-2 Tage

Akzeptanzkriterien:

  • ? POST /api/v1/documents/extract-swiss-qr-code im Swagger testbar
  • ? Swiss QR Code wird von letzter Seite extrahiert
  • ? Alle Swiss QR Bill Felder geparst (Standard 2.0)
  • ? Referenzen durchgeschliffen
  • ? Fehler wenn kein QR Code gefunden
  • ? 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
17.01.2025 PHASENPLAN ?? Feature-Reihenfolge geändert - Neues Feature 2: ExtractSwissQrCode (Swiss QR Bill Standard 2.0) eingefügt. Alte Features 2-5 werden zu Features 3-6.
17.01.2025 Feature 2 - ExtractSwissQrCode ?? GESTARTET - Swiss QR Code Extraktion von letzter PDF-Seite (DevExpress + Codecrete.SwissQRBill.Generator)

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