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

Refactor WorkflowsClient for unified result handling

Browse Source 
Refactored `ExtractSwissQrCodeAsync` to `InspectSwissQrCodeAsync`, introducing `SwissQrCodeResult` to encapsulate both validation and extraction results. Removed `throwIfInvalid` parameter, ensuring validation details are always returned without exceptions. Added extension methods for file path handling to improve usability.

Updated tests to reflect the new behavior, ensuring extraction is never attempted on invalid documents and validation results are always populated. Simplified API surface by removing redundant overloads and improving stream handling. Enhanced documentation and performed general code cleanup for better maintainability.
This commit is contained in:
tekh
2026-08-31 14:44:57 +02:00
parent 71dd32f11c
commit 092d283a2b
4 changed files with 148 additions and 371 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
DocumentService.Client/Interfaces/IWorkflowsClient.cs
View File

@@ -1,4 +1,5 @@
using DocumentService.Application.Common.DTOs;
using DocumentService.Client.Models.Results;
namespace DocumentService.Client.Interfaces;
@@ -9,51 +10,33 @@ namespace DocumentService.Client.Interfaces;
public interface IWorkflowsClient
{
/// <summary>
/// Validates the PDF and extracts its Swiss QR Code in a single call.
/// Validation runs first; extraction is only attempted on valid documents.
/// Validates the PDF and attempts Swiss QR Code extraction in a single call,
/// returning both results together. The method never throws on invalid documents –
/// the caller receives the full <see cref="PdfValidationResult"/> regardless of outcome,
/// enabling detailed logging, diagnostics, or batch processing without try/catch.
/// </summary>
/// <param name="pdfBytes">PDF file as byte array.</param>
/// <param name="raw">
/// <c>false</c> (default) – returns a parsed <see cref="SwissQrCodeExtractionResult.Bill"/> object.<br/>
/// <c>true</c> – returns raw QR text lines without parsing.
/// </param>
/// <param name="throwIfInvalid">
/// <c>true</c> (default) – throws <see cref="InvalidOperationException"/> when the PDF fails validation.<br/>
/// <c>false</c> – returns <c>null</c> instead, allowing the caller to handle the case without a try/catch.
/// </param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>
/// Swiss QR Code extraction result, or <c>null</c> if the document is invalid and
/// <paramref name="throwIfInvalid"/> is <c>false</c>.
/// A <see cref="SwissQrCodeResult"/> containing the <see cref="PdfValidationResult"/>
/// (always populated) and the <see cref="SwissQrCodeExtractionResult"/> (<c>null</c> if the
/// document was invalid).
/// </returns>
/// <exception cref="InvalidOperationException">
/// Thrown when the PDF fails validation and <paramref name="throwIfInvalid"/> is <c>true</c>.
/// </exception>
Task<SwissQrCodeExtractionResult?> ExtractSwissQrCodeAsync(
Task<SwissQrCodeResult> InspectSwissQrCodeAsync(
byte[] pdfBytes,
bool raw = false,
bool throwIfInvalid = true,
CancellationToken cancellationToken = default);
/// <inheritdoc cref="ExtractSwissQrCodeAsync(byte[], bool, bool, CancellationToken)"/>
/// <inheritdoc cref="InspectSwissQrCodeAsync(byte[], bool, CancellationToken)"/>
/// <param name="pdfStream">PDF file as a stream.</param>
/// <param name="raw"><inheritdoc cref="ExtractSwissQrCodeAsync(byte[], bool, bool, CancellationToken)" path="/param[@name='raw']"/></param>
/// <param name="throwIfInvalid"><inheritdoc cref="ExtractSwissQrCodeAsync(byte[], bool, bool, CancellationToken)" path="/param[@name='throwIfInvalid']"/></param>
/// <param name="raw"><inheritdoc cref="InspectSwissQrCodeAsync(byte[], bool, CancellationToken)" path="/param[@name=''raw'']"/></param>
/// <param name="cancellationToken">Cancellation token.</param>
Task<SwissQrCodeExtractionResult?> ExtractSwissQrCodeAsync(
Task<SwissQrCodeResult> InspectSwissQrCodeAsync(
Stream pdfStream,
bool raw = false,
bool throwIfInvalid = true,
CancellationToken cancellationToken = default);
/// <inheritdoc cref="ExtractSwissQrCodeAsync(byte[], bool, bool, CancellationToken)"/>
/// <param name="filePath">Absolute or relative path to the PDF file.</param>
/// <param name="raw"><inheritdoc cref="ExtractSwissQrCodeAsync(byte[], bool, bool, CancellationToken)" path="/param[@name='raw']"/></param>
/// <param name="throwIfInvalid"><inheritdoc cref="ExtractSwissQrCodeAsync(byte[], bool, bool, CancellationToken)" path="/param[@name='throwIfInvalid']"/></param>
/// <param name="cancellationToken">Cancellation token.</param>
Task<SwissQrCodeExtractionResult?> ExtractSwissQrCodeAsync(
string filePath,
bool raw = false,
bool throwIfInvalid = true,
CancellationToken cancellationToken = default);
}