From ec76014ce764bbc395c19929d779de61550e4da4 Mon Sep 17 00:00:00 2001 From: Developer 02 Date: Thu, 10 Apr 2025 16:07:08 +0200 Subject: [PATCH] Verbesserung von EnvelopeReceiverController mit neuen Funktionen MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Die Klasse EnvelopeReceiverController wurde aktualisiert, um die Funktionalität und Dokumentation zu verbessern. Es wurde eine neue using-Direktive hinzugefügt und die Namespace-Deklaration verschoben. Einführung der XML-Dokumentation in deutscher Sprache für mehr Klarheit. Die GetEnvelopeReceiver-Methode wurde so geändert, dass sie einen ReadEnvelopeReceiverQuery-Parameter akzeptiert, wodurch ihre Signatur verbessert wurde. Verbesserte Fehlerbehandlung und Protokollierung bei allen Methoden. GetSecretAsync hinzugefügt, um geheime Informationen nach UUID abzurufen. CreateAsync wurde aktualisiert, um die createEnvelopeQuery über den Mediator zu senden und einen akzeptierten Status zurückzugeben. --- .../Controllers/EnvelopeReceiverController.cs | 285 ++++++++++-------- 1 file changed, 161 insertions(+), 124 deletions(-) diff --git a/EnvelopeGenerator.GeneratorAPI/Controllers/EnvelopeReceiverController.cs b/EnvelopeGenerator.GeneratorAPI/Controllers/EnvelopeReceiverController.cs index c73d791c..244ddf71 100644 --- a/EnvelopeGenerator.GeneratorAPI/Controllers/EnvelopeReceiverController.cs +++ b/EnvelopeGenerator.GeneratorAPI/Controllers/EnvelopeReceiverController.cs @@ -1,153 +1,190 @@ using DigitalData.Core.DTO; using EnvelopeGenerator.Application.Contracts.Services; using EnvelopeGenerator.Application.EnvelopeReceivers.Commands.Create; +using EnvelopeGenerator.Application.EnvelopeReceivers.Queries.Read; using MediatR; using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Mvc; -namespace EnvelopeGenerator.GeneratorAPI.Controllers -{ - [Route("api/[controller]")] - [Authorize] - [ApiController] - public class EnvelopeReceiverController : ControllerBase - { - private readonly ILogger _logger; - - private readonly IEnvelopeReceiverService _erService; +namespace EnvelopeGenerator.GeneratorAPI.Controllers; - private readonly IMediator _mediator; - - public EnvelopeReceiverController(ILogger logger, IEnvelopeReceiverService envelopeReceiverService, IMediator mediator) - { - _logger = logger; - _erService = envelopeReceiverService; - _mediator = mediator; - } - - [HttpGet] - public async Task GetEnvelopeReceiver([FromQuery] int? min_status = null, [FromQuery] int? max_status = null, [FromQuery] int[]? ignore_status = null) - { - try - { - var username = User.GetUsername(); +/// +/// Controller für die Verwaltung von Umschlagempfängern. +/// +/// +/// Dieser Controller bietet Endpunkte für das Abrufen und Verwalten von Umschlagempfängerdaten. +/// +[Route("api/[controller]")] +[Authorize] +[ApiController] +public class EnvelopeReceiverController : ControllerBase +{ + private readonly ILogger _logger; - if (username is null) - { - _logger.LogError(@"Envelope Receiver dto cannot be sent because username claim is null. Potential authentication and authorization error. The value of other claims are [id: {id}], [username: {username}], [name: {name}], [prename: {prename}], [email: {email}].", - User.GetId(), User.GetUsername(), User.GetName(), User.GetPrename(), User.GetEmail()); - return StatusCode(StatusCodes.Status500InternalServerError); - } + private readonly IEnvelopeReceiverService _erService; - ignore_status ??= Array.Empty(); + private readonly IMediator _mediator; - return await _erService.ReadByUsernameAsync(username: username, min_status: min_status, max_status: max_status, ignore_statuses: ignore_status).ThenAsync( - Success: Ok, - Fail: IActionResult (msg, ntc) => - { - _logger.LogNotice(ntc); - return StatusCode(StatusCodes.Status500InternalServerError, msg); - }); - } - catch(Exception ex) - { - _logger.LogError(ex, "An unexpected error occurred. {message}", ex.Message); - return new StatusCodeResult(StatusCodes.Status500InternalServerError); - } - } + /// + /// Konstruktor für den EnvelopeReceiverController. + /// + /// Logger-Instanz zur Protokollierung von Informationen und Fehlern. + /// Service zur Verwaltung von Umschlagempfängern. + /// Mediator-Instanz zur Verarbeitung von Befehlen und Abfragen. + public EnvelopeReceiverController(ILogger logger, IEnvelopeReceiverService envelopeReceiverService, IMediator mediator) + { + _logger = logger; + _erService = envelopeReceiverService; + _mediator = mediator; + } - [HttpGet("receiver-name/{mail}")] - public async Task GetReceiverName([FromRoute] string mail) + /// + /// Ruft eine Liste von Umschlagempfängern basierend auf den angegebenen Abfrageparametern ab. + /// + /// Die Abfrageparameter, die den Status und andere Filterkriterien enthalten. + /// Eine HTTP-Antwort mit der Liste der gefundenen Umschlagempfänger oder einem Fehlerstatus. + /// + /// Dieser Endpunkt ermöglicht es, Umschlagempfänger basierend auf dem Benutzernamen und optionalen Statusfiltern abzurufen. + /// Wenn der Benutzername nicht ermittelt werden kann, wird ein Serverfehler zurückgegeben. + /// + [HttpGet] + public async Task GetEnvelopeReceiver([FromQuery] ReadEnvelopeReceiverQuery envelopeReceiver) + { + try { - try - { - return await _erService.ReadLastUsedReceiverNameByMail(mail).ThenAsync( - Success: res => res is null ? Ok(string.Empty) : Ok(res), - Fail: IActionResult (msg, ntc) => - { - if (ntc.HasFlag(Flag.NotFound)) - return NotFound(); + var username = User.GetUsername(); - _logger.LogNotice(ntc); - return StatusCode(StatusCodes.Status500InternalServerError); - }); - } - catch(Exception ex) + if (username is null) { - _logger.LogError(ex, "{message}", ex.Message); + _logger.LogError(@"Envelope Receiver dto cannot be sent because username claim is null. Potential authentication and authorization error. The value of other claims are [id: {id}], [username: {username}], [name: {name}], [prename: {prename}], [email: {email}].", + User.GetId(), User.GetUsername(), User.GetName(), User.GetPrename(), User.GetEmail()); return StatusCode(StatusCodes.Status500InternalServerError); } - } - [HttpGet("secret")] - [Authorize] - public async Task GetSecretAsync([FromQuery] string uuid) - { - try - { - return await _erService.ReadWithSecretByUuidAsync(uuid: uuid).ThenAsync( + return await _erService.ReadByUsernameAsync(username: username, min_status: envelopeReceiver.Status.Min, max_status: envelopeReceiver.Status.Min, ignore_statuses: envelopeReceiver.Status.Ignore ?? Array.Empty()).ThenAsync( Success: Ok, Fail: IActionResult (msg, ntc) => { _logger.LogNotice(ntc); - return StatusCode(StatusCodes.Status500InternalServerError); + return StatusCode(StatusCodes.Status500InternalServerError, msg); }); - } - catch (Exception ex) - { - _logger.LogError(ex, "{message}", ex.Message); - return StatusCode(StatusCodes.Status500InternalServerError); - } } + catch(Exception ex) + { + _logger.LogError(ex, "An unexpected error occurred. {message}", ex.Message); + return new StatusCodeResult(StatusCodes.Status500InternalServerError); + } + } + + /// + /// Ruft den Namen des letzten verwendeten Empfängers basierend auf der angegebenen E-Mail-Adresse ab. + /// + /// Die E-Mail-Adresse des Empfängers. + /// Eine HTTP-Antwort mit dem Namen des Empfängers oder einem Fehlerstatus. + /// + /// Dieser Endpunkt ermöglicht es, den Namen des letzten Empfängers abzurufen, der mit der angegebenen E-Mail-Adresse verknüpft ist. + /// Wenn kein Empfänger gefunden wird, wird ein leerer String zurückgegeben. + /// + [HttpGet("receiver-name/{mail}")] + public async Task GetReceiverName([FromRoute] string mail) + { + try + { + return await _erService.ReadLastUsedReceiverNameByMail(mail).ThenAsync( + Success: res => res is null ? Ok(string.Empty) : Ok(res), + Fail: IActionResult (msg, ntc) => + { + if (ntc.HasFlag(Flag.NotFound)) + return NotFound(); + + _logger.LogNotice(ntc); + return StatusCode(StatusCodes.Status500InternalServerError); + }); + } + catch(Exception ex) + { + _logger.LogError(ex, "{message}", ex.Message); + return StatusCode(StatusCodes.Status500InternalServerError); + } + } - /// - /// Datenübertragungsobjekt mit Informationen zu Umschlägen, Empfängern und Unterschriften. - /// - /// - /// Token to cancel the operation - /// HTTP-Antwort - /// - /// Sample request: - /// - /// POST /api/envelope - /// { - /// "title": "Vertragsdokument", - /// "message": "Bitte unterschreiben Sie dieses Dokument.", - /// "document": { - /// "dataAsBase64": "dGVzdC1iYXNlNjQtZGF0YQ==" - /// }, - /// "receivers": [ - /// { - /// "emailAddress": "example@example.com", - /// "signatures": [ - /// { - /// "x": 100, - /// "y": 200, - /// "page": 1 - /// } - /// ], - /// "name": "Max Mustermann", - /// "phoneNumber": "+49123456789" - /// } - /// ], - /// "language": "de-DE", - /// "expiresWhen": "2025-12-31T23:59:59Z", - /// "expiresWarningWhen": "2025-12-24T23:59:59Z", - /// "contractType": 1, - /// "tfaEnabled": false - /// } - /// - /// - /// Envelope-Erstellung und Sendeprozessbefehl erfolgreich - /// Wenn ein Fehler im HTTP-Body auftritt - /// Wenn kein autorisierter Token vorhanden ist - /// Es handelt sich um einen unerwarteten Fehler. Die Protokolle sollten überprüft werden. - [Authorize] - [HttpPost] - public async Task CreateAsync([FromBody] CreateEnvelopeCommand createEnvelopeQuery, CancellationToken cancellationToken) + /// + /// Ruft geheime Informationen basierend auf der angegebenen UUID ab. + /// + /// Die eindeutige Kennung (UUID), die verwendet wird, um die geheimen Informationen abzurufen. + /// Eine HTTP-Antwort mit den geheimen Informationen oder einem Fehlerstatus. + /// + /// Dieser Endpunkt ermöglicht es, geheime Informationen zu einem Umschlagempfänger basierend auf der UUID abzurufen. + /// Wenn keine Informationen gefunden werden, wird ein entsprechender Fehlerstatus zurückgegeben. + /// + [HttpGet("secret")] + [Authorize] + public async Task GetSecretAsync([FromQuery] string uuid) + { + try + { + return await _erService.ReadWithSecretByUuidAsync(uuid: uuid).ThenAsync( + Success: Ok, + Fail: IActionResult (msg, ntc) => + { + _logger.LogNotice(ntc); + return StatusCode(StatusCodes.Status500InternalServerError); + }); + } + catch (Exception ex) { - await _mediator.Send(createEnvelopeQuery, cancellationToken); - return Accepted(); + _logger.LogError(ex, "{message}", ex.Message); + return StatusCode(StatusCodes.Status500InternalServerError); } } + + /// + /// Datenübertragungsobjekt mit Informationen zu Umschlägen, Empfängern und Unterschriften. + /// + /// + /// Token to cancel the operation + /// HTTP-Antwort + /// + /// Sample request: + /// + /// POST /api/envelope + /// { + /// "title": "Vertragsdokument", + /// "message": "Bitte unterschreiben Sie dieses Dokument.", + /// "document": { + /// "dataAsBase64": "dGVzdC1iYXNlNjQtZGF0YQ==" + /// }, + /// "receivers": [ + /// { + /// "emailAddress": "example@example.com", + /// "signatures": [ + /// { + /// "x": 100, + /// "y": 200, + /// "page": 1 + /// } + /// ], + /// "name": "Max Mustermann", + /// "phoneNumber": "+49123456789" + /// } + /// ], + /// "language": "de-DE", + /// "expiresWhen": "2025-12-31T23:59:59Z", + /// "expiresWarningWhen": "2025-12-24T23:59:59Z", + /// "contractType": 1, + /// "tfaEnabled": false + /// } + /// + /// + /// Envelope-Erstellung und Sendeprozessbefehl erfolgreich + /// Wenn ein Fehler im HTTP-Body auftritt + /// Wenn kein autorisierter Token vorhanden ist + /// Es handelt sich um einen unerwarteten Fehler. Die Protokolle sollten überprüft werden. + [Authorize] + [HttpPost] + public async Task CreateAsync([FromBody] CreateEnvelopeCommand createEnvelopeQuery, CancellationToken cancellationToken) + { + await _mediator.Send(createEnvelopeQuery, cancellationToken); + return Accepted(); + } } \ No newline at end of file