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

492 lines
14 KiB
Markdown
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<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 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