# ?? 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.*