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

533 lines
16 KiB
Markdown
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<T>)
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