Add documentation for DocumentOperator service
Added `CONTROLLER_ENDPOINTS.md` to define REST API endpoints and `REQUIRED_FEATURES.md` to outline required functions and features for the `DocumentOperator` service. These documents include detailed specifications for controllers, input/output formats, usage scenarios, and technical requirements. Updated `DocumentOperator.sln` to include the new documentation files under a "Solution Items" section for better visibility. Defined a prioritization strategy for feature implementation, technical requirements, and a comprehensive test strategy. Referenced relevant standards (e.g., PDF/A, ZUGFeRD) and documented usage of the DevExpress Office File API.
This commit is contained in:
348
CONTROLLER_ENDPOINTS.md
Normal file
348
CONTROLLER_ENDPOINTS.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# DocumentOperator - Controller & Endpoint Specification
|
||||
|
||||
**Project:** DocumentService (DOC)
|
||||
**Ticket:** DOC-1 - GDPicture and Nutrient Replacing
|
||||
**Owner:** Hakan Tek
|
||||
**Date:** July 3, 2026
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This specification defines the controller structure and REST API endpoints for the DocumentOperator service.
|
||||
|
||||
---
|
||||
|
||||
## PdfValidationController
|
||||
|
||||
### Endpoint: PDF Validation
|
||||
**Route:** `POST /api/pdf/validation/validate`
|
||||
**Function:** Checks whether the file is a valid PDF, whether it is corrupted, and returns basic information
|
||||
|
||||
**Input:**
|
||||
- PDF file (multipart/form-data)
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"isValid": bool,
|
||||
"pdfVersion": string,
|
||||
"pageCount": int,
|
||||
"fileSize": long,
|
||||
"encrypted": bool,
|
||||
"errors": string[]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** All products - basic PDF input check
|
||||
|
||||
---
|
||||
|
||||
### Endpoint: PDF/A Validation
|
||||
**Route:** `POST /api/pdf/validation/validate-pdfa`
|
||||
**Function:** PDF/A conformance check (embedded fonts, encryption, JavaScript, etc.)
|
||||
|
||||
**Input:**
|
||||
- PDF file (multipart/form-data)
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"isValid": bool,
|
||||
"pdfaVersion": string,
|
||||
"pageCount": int,
|
||||
"errors": string[],
|
||||
"warnings": string[]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** taskFLOW, eParser - ensuring PDF/A conformance
|
||||
|
||||
---
|
||||
|
||||
## PdfAttachmentController
|
||||
|
||||
### Endpoint: Attachment Check
|
||||
**Route:** `POST /api/pdf/attachments/check`
|
||||
**Function:** Detects whether embedded files (e.g. ZUGFeRD XML) are present in the PDF
|
||||
|
||||
**Input:**
|
||||
- PDF file (multipart/form-data)
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"hasAttachments": bool,
|
||||
"attachmentCount": int,
|
||||
"attachments": [
|
||||
{
|
||||
"fileName": string,
|
||||
"mimeType": string,
|
||||
"size": long
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** eParser (ZUGFeRD), ErgebnisberichtCreator
|
||||
|
||||
---
|
||||
|
||||
### Endpoint: Attachment Extraction
|
||||
**Route:** `POST /api/pdf/attachments/extract`
|
||||
**Function:** Extracts all embedded files from the PDF and saves them to the specified path
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"file": "PDF (multipart/form-data)",
|
||||
"outputPath": string
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"success": bool,
|
||||
"extractedFiles": [
|
||||
{
|
||||
"fileName": string,
|
||||
"savedPath": string,
|
||||
"size": long
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** eParser (ZUGFeRD XML extraction)
|
||||
|
||||
---
|
||||
|
||||
## PdfOperationsController
|
||||
|
||||
### Endpoint: PDF Merge
|
||||
**Route:** `POST /api/pdf/operations/merge`
|
||||
**Function:** Merges multiple PDFs into a single file
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"sourceFiles": string[],
|
||||
"outputPath": string
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"success": bool,
|
||||
"outputPath": string,
|
||||
"pageCount": int,
|
||||
"fileSize": long
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** signFLOW (Envelope Generator), ErgebnisberichtCreator, ResultHandler (windream)
|
||||
|
||||
---
|
||||
|
||||
### Endpoint: PDF Stamp
|
||||
**Route:** `POST /api/pdf/operations/stamp`
|
||||
**Function:** Adds stamps to PDF pages (APPROVED, CONFIDENTIAL, etc.)
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"file": "PDF (multipart/form-data)",
|
||||
"stamp": {
|
||||
"text": string,
|
||||
"position": string,
|
||||
"pages": string,
|
||||
"color": string,
|
||||
"opacity": float
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"success": bool,
|
||||
"outputPath": string
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** ErgebnisberichtCreator
|
||||
|
||||
---
|
||||
|
||||
### Endpoint: PDF Annotate
|
||||
**Route:** `POST /api/pdf/operations/annotate`
|
||||
**Function:** Adds comments, highlights, and markings to the PDF
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"file": "PDF (multipart/form-data)",
|
||||
"annotations": [
|
||||
{
|
||||
"type": string,
|
||||
"page": int,
|
||||
"position": object,
|
||||
"text": string
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"success": bool,
|
||||
"outputPath": string
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** signFLOW (Envelope Generator)
|
||||
|
||||
---
|
||||
|
||||
## PdfRenderController
|
||||
|
||||
### Endpoint: PDF Preview
|
||||
**Route:** `POST /api/pdf/render/preview`
|
||||
**Function:** Renders PDF pages as PNG/JPEG for preview
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"file": "PDF (multipart/form-data)",
|
||||
"page": int,
|
||||
"format": string,
|
||||
"dpi": int
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"images": [
|
||||
{
|
||||
"page": int,
|
||||
"base64": string,
|
||||
"width": int,
|
||||
"height": int
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** taskFLOW, fileFLOW, easyFLOW, orgFLOW - PDF preview
|
||||
|
||||
---
|
||||
|
||||
## PdfConversionController
|
||||
|
||||
### Endpoint: Convert PDF to PDF/A
|
||||
**Route:** `POST /api/pdf/conversion/to-pdfa`
|
||||
**Function:** Converts a standard PDF to PDF/A
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"file": "PDF (multipart/form-data)",
|
||||
"pdfaLevel": string
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"success": bool,
|
||||
"outputPath": string,
|
||||
"pdfaVersion": string
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** taskFLOW (optional conversion)
|
||||
|
||||
---
|
||||
|
||||
### Endpoint: Convert PDF/A to PDF
|
||||
**Route:** `POST /api/pdf/conversion/from-pdfa`
|
||||
**Function:** Converts PDF/A to a standard PDF
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"file": "PDF (multipart/form-data)"
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"success": bool,
|
||||
"outputPath": string
|
||||
}
|
||||
```
|
||||
|
||||
**Usage:** taskFLOW (optional conversion)
|
||||
|
||||
---
|
||||
|
||||
## Technical Specifications
|
||||
|
||||
### Framework Support
|
||||
- ✓ .NET Core (3.1+, 6.0+, 8.0+)
|
||||
- ✓ .NET Framework (4.7.2+, 4.8+)
|
||||
|
||||
### Client Usage
|
||||
The service can be used on the client side **without manual HTTP response handling**:
|
||||
- Provide REST client wrapper
|
||||
- SDK for C# clients
|
||||
- Automatic serialization/deserialization
|
||||
- Abstracted error handling
|
||||
|
||||
**Example Client SDK:**
|
||||
```csharp
|
||||
var client = new DocumentOperatorClient("https://api.example.com");
|
||||
var result = await client.Pdf.Validation.ValidateAsync(pdfFile);
|
||||
if (result.IsValid) { ... }
|
||||
```
|
||||
|
||||
### Response Format
|
||||
- Default: JSON
|
||||
- Errors: HTTP Status Codes (400, 404, 500) + JSON error object
|
||||
- Success: HTTP 200 + JSON response
|
||||
|
||||
### Authentication
|
||||
- API Key (Header: `X-API-Key`)
|
||||
- Optional: OAuth2/JWT for advanced scenarios
|
||||
|
||||
### Swagger/OpenAPI
|
||||
- Complete API documentation
|
||||
- Interactive test UI
|
||||
- Code generation for clients
|
||||
|
||||
---
|
||||
|
||||
## Prioritization
|
||||
|
||||
### Phase 1 (Priority)
|
||||
1. PdfValidationController - both endpoints
|
||||
2. PdfAttachmentController - both endpoints
|
||||
3. PdfOperationsController - Merge endpoint
|
||||
|
||||
### Phase 2
|
||||
4. PdfOperationsController - Stamp & Annotate
|
||||
5. PdfRenderController - Preview
|
||||
|
||||
### Phase 3
|
||||
6. PdfConversionController - both endpoints
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** July 3, 2026
|
||||
**Author:** Hakan Tek
|
||||
**Status:** Draft - Awaiting Feedback
|
||||
Reference in New Issue
Block a user