EnvelopeGenerator/EnvelopeGenerator.API/Controllers/HistoryController.cs

using MediatR;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Caching.Memory;
using EnvelopeGenerator.Application.Histories.Queries;
using EnvelopeGenerator.Domain.Constants;
using EnvelopeGenerator.Application.Common.Extensions;

namespace EnvelopeGenerator.API.Controllers;

/// <summary>
/// Dieser Controller stellt Endpunkte für den Zugriff auf die Umschlaghistorie bereit.
/// </summary>
[Route("api/[controller]")]
[ApiController]
[Authorize]
public class HistoryController : ControllerBase
{
    private readonly IMemoryCache _memoryCache;

    private readonly IMediator _mediator;

    /// <summary>
    /// Konstruktor für den HistoryController.
    /// </summary>
    /// <param name="memoryCache"></param>
    /// <param name="mediator"></param>
    public HistoryController(IMemoryCache memoryCache, IMediator mediator)
    {
        _memoryCache = memoryCache;
        _mediator = mediator;
    }

    /// <summary>
    /// Gibt alle möglichen Verweise auf alle möglichen Include in einem Verlaufsdatensatz zurück. (z. B. DocumentSigned bezieht sich auf Receiver.)
    /// Dies wird hinzugefügt, damit Client-Anwendungen sich selbst auf dem neuesten Stand halten können.
    /// 1 - Sender:
    /// Historische Datensätze über den Include der Empfänger. Diese haben Statuscodes, die mit 1* beginnen.
    /// 2 - Receiver:
    /// Historische Datensätze, die sich auf den Include des Absenders beziehen. Sie haben Statuscodes, die mit 2* beginnen.
    /// 3 - System:
    /// Historische Datensätze, die sich auf den allgemeinen Zustand des Umschlags beziehen. Diese haben Statuscodes, die mit 3* beginnen.
    /// 4 - Unknown: 
    /// Ein unbekannter Datensatz weist auf einen möglichen Mangel oder eine Unstimmigkeit im Aktualisierungsprozess der Anwendung hin.
    /// </summary>
    /// <returns></returns>
    /// <response code="200"></response>
    [HttpGet("related")]
    [Authorize]
    public IActionResult GetReferenceTypes(ReferenceType? referenceType = null)
    {
        return referenceType is null 
            ? Ok(_memoryCache.GetEnumAsDictionary<ReferenceType>("gen.api", ReferenceType.Unknown))
            : Ok(referenceType.ToString());
    }

    /// <summary>
    /// Gibt alle möglichen Include in einem Verlaufsdatensatz zurück.
    /// Dies wird hinzugefügt, damit Client-Anwendungen sich selbst auf dem neuesten Stand halten können.
    /// 1003: EnvelopeQueued
    /// 1006: EnvelopeCompletelySigned
    /// 1007: EnvelopeReportCreated
    /// 1008: EnvelopeArchived
    /// 1009: EnvelopeDeleted
    /// 10007: EnvelopeRejected
    /// 10009: EnvelopeWithdrawn
    /// 2001: AccessCodeRequested
    /// 2002: AccessCodeCorrect
    /// 2003: AccessCodeIncorrect
    /// 2004: DocumentOpened
    /// 2005: DocumentSigned
    /// 2006: DocumentForwarded
    /// 2007: DocumentRejected
    /// 2008: EnvelopeShared
    /// 2009: EnvelopeViewed
    /// 3001: MessageInvitationSent (Wird von Trigger verwendet)
    /// 3002: MessageAccessCodeSent
    /// 3003: MessageConfirmationSent
    /// 3004: MessageDeletionSent
    /// 3005: MessageCompletionSent
    /// </summary>
    /// <param name="status">
    /// Abfrageparameter, der angibt, auf welche Referenz sich der Include bezieht.
    /// 1 - Sender: Historische Datensätze, die sich auf den Include des Absenders beziehen. Sie haben Statuscodes, die mit 1* beginnen.
    /// 2 - Receiver: Historische Datensätze über den Include der Empfänger. Diese haben Statuscodes, die mit 2* beginnen.
    /// 3 - System: Diese werden durch Datenbank-Trigger aktualisiert und sind in den Tabellen EnvelopeHistory und EmailOut zu finden.Sie arbeiten 
    /// integriert mit der Anwendung EmailProfiler, um E-Mails zu versenden und haben die Codes, die mit 3* beginnen.
    /// </param>
    /// <returns>Gibt die HTTP-Antwort zurück.</returns>
    /// <response code="200"></response>
    [HttpGet("status")]
    [Authorize]
    public IActionResult GetEnvelopeStatus([FromQuery] EnvelopeStatus? status = null)
    {
        return status is null
            ? Ok(_memoryCache.GetEnumAsDictionary<EnvelopeStatus>("gen.api", Status.NonHist, Status.RelatedToFormApp))
            : Ok(status.ToString());
    }

    /// <summary>
    /// Ruft die gesamte Umschlaghistorie basierend auf den angegebenen Abfrageparametern ab.
    /// </summary>
    /// <param name="historyQuery">Die Abfrageparameter, die die Filterkriterien für die Umschlaghistorie definieren.</param>
    /// <param name="cancel"></param>
    /// <returns>Eine Liste von Historieneinträgen, die den angegebenen Kriterien entsprechen, oder nur der letzte Eintrag.</returns>
    /// <response code="200">Die Anfrage war erfolgreich, und die Umschlaghistorie wird zurückgegeben.</response>
    /// <response code="400">Die Anfrage war ungültig oder unvollständig.</response>
    /// <response code="401">Der Benutzer ist nicht authentifiziert.</response>
    /// <response code="403">Der Benutzer hat keine Berechtigung, auf die Ressource zuzugreifen.</response>
    /// <response code="500">Ein unerwarteter Fehler ist aufgetreten.</response>
    [HttpGet]
    [Authorize]
    public async Task<IActionResult> GetAllAsync([FromQuery] ReadHistoryQuery historyQuery, CancellationToken cancel)
    {
        var history = await _mediator.Send(historyQuery, cancel).ThrowIfEmpty(Exceptions.NotFound);
        return Ok((historyQuery.OnlyLast) ? history.MaxBy(h => h.AddedWhen) : history);
    }
}