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

docs: Update API specification based on Marvin/Marlon feedback

Browse Source 
CONTROLLER_ENDPOINTS.md changes:

  - Binary stream output for all operations (NO outputPath, NO base64)

  - PDF Operations: merge, stamp, annotate → return application/pdf stream

  - PDF Conversion: to-pdfa, from-pdfa → return application/pdf stream

  - Attachment Extraction: extract → return application/zip stream

  - Add Attachment endpoint (Phase 2): embed files in PDF/PDF/A-3

  - Swiss QR Code endpoint documented (already implemented)

  - PdfRenderController REMOVED (moved to .NET client library)

AGENTS.md changes:

  - Current Status: SwissQrCodeController ✅ DONE (2 tests)

  - Current Status: PdfValidationController ✅ Partial (4 tests)

  - Phase reorganization:

    - Phase 1: validate, validate-pdfa, check, extract (SwissQR), extract (attachments), merge

    - Phase 2: stamp, annotate, add-attachment

    - Phase 3: to-pdfa, from-pdfa

  - Removed PdfRenderController from all phases

Design decisions (team consensus):

  - Server endpoints stay granular (validate, check, extract separate)

  - Combined operations (validateANDextract) → .NET client library

  - Binary streams avoid filesystem dependencies

  - No base64 overhead (~33%), client library handles conversions

Result: Clean API spec, memory-based operations, client convenience layer
This commit is contained in:
tekh
2026-07-08 15:46:10 +02:00
parent 45bc90b8b8
commit dc0af68d26
2 changed files with 142 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
AGENTS.md
View File

@@ -177,7 +177,7 @@ All files for a feature live together. Do NOT create separate Commands/, Handler
- ✅ All features currently work without authentication
**When to implement:**
After completing all Phase 1-3 controllers (PdfValidation, PdfAttachment, PdfOperations, PdfRender, PdfConversion), then add multi-tenancy to ALL endpoints in one refactoring phase.
After completing all Phase 1-3 controllers (PdfValidation, PdfAttachment, SwissQrCode, PdfOperations, PdfConversion), then add multi-tenancy to ALL endpoints in one refactoring phase.
---
@@ -245,30 +245,41 @@ Do NOT add `if (result.IsSuccess)` checks. Throw exceptions for errors. The midd
1. `PdfValidationController` – 2 endpoints
- `POST /api/pdf/validation/validate` (Basic PDF validation)
- `POST /api/pdf/validation/validate-pdfa` (PDF/A conformance)
2. `PdfAttachmentController` – 2 endpoints
2. `PdfAttachmentController` – check endpoint
- `POST /api/pdf/attachments/check` (Attachment detection)
- `POST /api/pdf/attachments/extract` (Extract attachments)
3. `PdfOperationsController` – Merge endpoint
3. `SwissQrCodeController` – extract endpoint
- `POST /api/swissqrcode/extract` (Swiss QR Bill extraction)
4. `PdfAttachmentController` – extract endpoint
- `POST /api/pdf/attachments/extract` (Extract attachments as ZIP)
5. `PdfOperationsController` – merge endpoint
- `POST /api/pdf/operations/merge` (Merge multiple PDFs)
**Phase 2:**
4. `PdfOperationsController` – Stamp & Annotate
5. `PdfRenderController` – Preview
6. `PdfOperationsController` – stamp & annotate
- `POST /api/pdf/operations/stamp` (Add stamps)
- `POST /api/pdf/operations/annotate` (Add annotations)
7. `PdfAttachmentController` – add attachment
- `POST /api/pdf/attachments/add` (Embed attachments in PDF/A-3)
**Phase 3:**
6. `PdfConversionController` – PDF ↔ PDF/A conversion
8. `PdfConversionController` – PDF ↔ PDF/A conversion
- `POST /api/pdf/conversion/to-pdfa` (Convert to PDF/A)
- `POST /api/pdf/conversion/from-pdfa` (Convert from PDF/A)
**Removed:**
- `PdfRenderController` – Moved to .NET client library (WinForms/WPF DevExpress controls)
### Current Status
| Controller | Status | Tests |
|-----------|--------|-------|
| **PdfValidationController** | ⏳ Pending | 0 |
| **PdfValidationController** | ✅ Partial (validate done, validate-pdfa pending) | 4 |
| **SwissQrCodeController** | ✅ DONE | 2 |
| **PdfAttachmentController** | ⏳ Pending | 0 |
| **PdfOperationsController** | ⏳ Pending | 0 |
| **PdfRenderController** | ⏳ Pending | 0 |
| **PdfConversionController** | ⏳ Pending | 0 |
**Legacy code exists** (`DocumentEndpoints.cs` with Minimal API + Base64 JSON), but **must be replaced** with Controllers + multipart/form-data.
**Note:** PdfRenderController removed - moved to .NET client library.
---