AppStd/DocumentService
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance ExtractSwissQrCode feature documentation

Browse Source 
Updated `DocumentEndpoints` to include detailed requirements, return values, and use case for the `ExtractSwissQrCode` endpoint.

Marked Feature 2 (`ExtractSwissQrCode`) as completed in `PHASENPLAN.md` and `ROADMAP.md`, summarizing achievements and outlining next steps for Feature 3 (`ExtractAttachments`).

Enhanced `ExtractSwissQrCodeRequest` and `ExtractSwissQrCodeResponse` DTOs with example JSON payloads for clarity.

Expanded `SwissQrCodeDataDto` and `AddressDataDto` with detailed field-level documentation to improve usability and adherence to Swiss QR Bill Standard 2.0.
This commit is contained in:
OlgunR
2026-06-26 08:58:25 +02:00
parent c5db216f15
commit 84c0a54c1e
5 changed files with 159 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
DocumentOperator.API/PHASENPLAN.md
View File

@@ -1,6 +1,6 @@
# ?? DocumentOperator - Phasenplan (Feature-Driven Development)
> **Stand:** 17.01.2025 | **Aktuell:** Feature 2 - ExtractSwissQrCode ? IN PROGRESS | **Projektdauer:** 6 Wochen
> **Stand:** 17.01.2025 | **Aktuell:** Feature 3 - ExtractAttachments ? NEXT | **Projektdauer:** 6 Wochen
---
@@ -9,8 +9,8 @@
| 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% |
| **W1-W2** | Feature 2: ExtractSwissQrCode | ? Abgeschlossen | 100% (Domain + Infrastructure + Application + API + Swagger fertig) |
| **W2** | Feature 3: ExtractAttachments | ? Nächstes Feature | 0% |
| **W2** | Feature 4: ApplyStamp | ? Geplant | 0% |
| **W3** | Feature 5: EmbedCertificate | ? Geplant | 0% |
| **W3** | Feature 6: ConcatenatePDFs (Async) | ? Geplant | 0% |
@@ -170,36 +170,46 @@
---
### WOCHE 1-2 - Feature 2: ExtractSwissQrCode | ? In Progress - 0%
### WOCHE 1-2 - Feature 2: ExtractSwissQrCode | ? ABGESCHLOSSEN - 100%
**Dauer:** ~1-2 Tage
**Status:** ? In Progress (gerade gestartet!)
**Status:** ? Abgeschlossen
**Endpoint:** POST /api/v1/documents/extract-swiss-qr-code
**Was wird gebaut:**
**Was wurde 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)
- **ZXing.Net.Bindings.Windows.Compatibility** (QR Code Detection)
- **Codecrete.SwissQRBill.Generator** (Swiss QR Code Parsing - Standard 2.0)
- **System.Drawing.Common** (Bitmap Support)
**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
- ? Step 2.1: Domain Layer (SwissQrCodeData Value Object) - ABGESCHLOSSEN
- ? Step 2.2: Infrastructure Layer (ISwissQrCodeProcessor + DevExpressSwissQrCodeProcessor + Library Integration) - ABGESCHLOSSEN
- ? Step 2.3: Application Layer (ExtractSwissQrCodeQuery + Handler + Validator + DTOs) - ABGESCHLOSSEN
- ? Step 2.4: API Layer (Endpoint + Exception Mapping + Integration Tests) - ABGESCHLOSSEN
- ? Step 2.5: Swagger Dokumentation (XML Comments + Examples) - ABGESCHLOSSEN
**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
- ? Fehler wenn kein QR Code gefunden (404 Not Found)
- ? Swagger-testbar
- ? Tests grün
- ? Tests grün (19/19)
**Ergebnis:**
- ? POST /api/v1/documents/extract-swiss-qr-code im Swagger testbar
- ? Nested Response Structure (References + SwissQrCodeData)
- ? SwissQrCodeNotFoundException wird zu 404 gemappt
- ? Unit Tests + Integration Tests grün (19/19)
- ? Clean Architecture eingehalten
- ? Swagger-Dokumentation vollständig
---
@@ -487,21 +497,19 @@
### 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
**Feature 3: ExtractAttachments** - **NEXT**
1. ?? Step 3.1: Domain Layer (Attachment Value Object)
2. ?? Step 3.2: Infrastructure Layer (IAttachmentProcessor + DevExpressAttachmentProcessor)
3. ?? Step 3.3: Application Layer (ExtractAttachmentsQuery + Handler + Validator + DTOs)
4. ?? Step 3.4: API Layer (Endpoint + Integration Tests)
5. ?? Step 3.5: Swagger Dokumentation
**Erwarteter Zeitaufwand:** ~1-2 Tage
**Erwarteter Zeitaufwand:** ~1 Tag
**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
- ? POST /api/v1/documents/extract-attachments im Swagger testbar
- ? Alle Attachments werden extrahiert
- ? Attachment-Metadaten werden zurückgegeben
- ? Alle Tests grün
- ? Clean Architecture eingehalten
@@ -523,7 +531,12 @@
| 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) |
| 17.01.2025 | **Feature 2 - Step 2.1** | ? **ABGESCHLOSSEN** - Domain Layer (SwissQrCodeData, AddressData, SwissQrCodeNotFoundException) |
| 17.01.2025 | **Feature 2 - Step 2.2** | ? **ABGESCHLOSSEN** - Infrastructure Layer (ISwissQrCodeProcessor, DevExpressSwissQrCodeProcessor, ZXing + Codecrete Integration) |
| 17.01.2025 | **Feature 2 - Step 2.3** | ? **ABGESCHLOSSEN** - Application Layer (ExtractSwissQrCodeQuery, Handler, Validator, Request/Response DTOs, Unit Tests) |
| 17.01.2025 | **Feature 2 - Step 2.4** | ? **ABGESCHLOSSEN** - API Layer (Endpoint, Exception Mapping, Integration Tests - 19/19 Tests grün) |
| 17.01.2025 | **Feature 2 - Step 2.5** | ? **ABGESCHLOSSEN** - Swagger Dokumentation (XML Comments, Examples, Endpoint Description) |
| 17.01.2025 | **Feature 2** | ? **KOMPLETT ABGESCHLOSSEN** - ExtractSwissQrCode Feature testbar im Swagger UI! (19/19 Tests grün) |
---