add XML documentation, closes #10
This commit is contained in:
parent
c536db0ef6
commit
be4ab681a4
@ -7,44 +7,130 @@ using System.Collections.Immutable;
|
||||
|
||||
namespace dopt.DeltaBarth.DataObjects
|
||||
{
|
||||
/// <summary>
|
||||
/// Eine verpackte Fehlermeldung, die vom API-Server zur Verfügung gestellt wurde.
|
||||
/// </summary>
|
||||
public record class ApiServerError
|
||||
{
|
||||
/// <summary>
|
||||
/// Statuscode der HTTP-Anfrage
|
||||
/// </summary>
|
||||
public required int status_code { get; init; }
|
||||
/// <summary>
|
||||
/// Fehlerbezeichnung
|
||||
/// </summary>
|
||||
public required string message { get; init; }
|
||||
/// <summary>
|
||||
/// optional: spezifischer Code als Text, der vom Server ausgegeben wurde
|
||||
/// </summary>
|
||||
public string? code { get; init; }
|
||||
/// <summary>
|
||||
/// optional: spezifische Hinweise als Text, der vom Server ausgegeben wurde
|
||||
/// </summary>
|
||||
public string? hints { get; init; }
|
||||
/// <summary>
|
||||
/// optional: spezifischer Typus als Text, der vom Server ausgegeben wurde
|
||||
/// </summary>
|
||||
public string? type { get; init; }
|
||||
/// <summary>
|
||||
/// optional: spezifischer Titel als Text, der vom Server ausgegeben wurde
|
||||
/// </summary>
|
||||
public string? title { get; init; }
|
||||
/// <summary>
|
||||
/// optional: spezifischer ID (vermutlich zur Nachverfolgung) als Text, der vom Server ausgegeben wurde
|
||||
/// </summary>
|
||||
public string? traceId { get; init; }
|
||||
}
|
||||
/// <summary>
|
||||
/// Status-Objekt: Gibt Aufschluss über Erfolg/Misserfolg einer Routine und beschreibt aufgetretene Fehler
|
||||
/// mit zusätzlichen Informationen
|
||||
/// </summary>
|
||||
public record class Status
|
||||
{
|
||||
/// <summary>
|
||||
/// bibliotheksinterner Fehlercode
|
||||
/// </summary>
|
||||
public required int code { get; init; }
|
||||
/// <summary>
|
||||
/// Fehlerbeschreibung oder Python-Exception-Name
|
||||
/// </summary>
|
||||
public required string description { get; init; }
|
||||
/// <summary>
|
||||
/// genauere Beschreibung oder Fehler-Inhalt
|
||||
/// </summary>
|
||||
public required string message { get; init; }
|
||||
/// <summary cref="ApiServerError">
|
||||
/// optional: eventuell aufgetretener API-Server-Fehler
|
||||
/// </summary>
|
||||
public ApiServerError? apiServerError { get; init; }
|
||||
|
||||
}
|
||||
/// <summary>
|
||||
/// Nutzerdaten zur API-Interaktion
|
||||
/// </summary>
|
||||
public record class Credentials
|
||||
{
|
||||
/// <summary>
|
||||
/// Nutzername
|
||||
/// </summary>
|
||||
public required string username { get; init; }
|
||||
/// <summary>
|
||||
/// Passwort
|
||||
/// </summary>
|
||||
public required string password { get; init; }
|
||||
/// <summary>
|
||||
/// Datenbank
|
||||
/// </summary>
|
||||
public required string database { get; init; }
|
||||
/// <summary>
|
||||
/// Mandant
|
||||
/// </summary>
|
||||
public required string mandant { get; init; }
|
||||
}
|
||||
/// <summary>
|
||||
/// Einzelergebnis der Umsatzprognose, 1 Eintrag von potenziell mehreren
|
||||
/// </summary>
|
||||
public record class UmsatzPrognoseEinzelergebnis
|
||||
{
|
||||
/// <summary>
|
||||
/// Jahr des Eintrags
|
||||
/// </summary>
|
||||
public required int jahr { get; init; }
|
||||
/// <summary>
|
||||
/// Monat des Eintrags
|
||||
/// </summary>
|
||||
public required int monat { get; init; }
|
||||
/// <summary>
|
||||
/// Prognosewert für den Umsatz
|
||||
/// </summary>
|
||||
public required decimal vorhersage { get; init; }
|
||||
}
|
||||
/// <summary>
|
||||
/// Sammlung von unterschiedlichen Einzelergebnissen
|
||||
/// <see cref="UmsatzPrognoseEinzelergebnis"/>
|
||||
/// </summary>
|
||||
public record class UmsatzPrognoseErgebnisse
|
||||
{
|
||||
/// <summary>
|
||||
/// unveränderliche Sammlung von Einzelergebnissen in Form eines Array
|
||||
/// </summary>
|
||||
public required ImmutableArray<UmsatzPrognoseEinzelergebnis> daten { get; init; }
|
||||
}
|
||||
/// <summary>
|
||||
/// Ausgabe der Prognose-Pipeline:
|
||||
/// enthält das Ergebnis als auch einen dazugehörigen Status
|
||||
/// </summary>
|
||||
public record class UmsatzPrognoseAusgabe
|
||||
{
|
||||
/// <summary>
|
||||
/// Sammlung von Prognosewerten
|
||||
/// <see cref="UmsatzPrognoseErgebnisse"/>
|
||||
/// </summary>
|
||||
public required UmsatzPrognoseErgebnisse response { get; init; }
|
||||
/// <summary>
|
||||
/// Status über den Erfolg/Misserfolg der Routine
|
||||
/// <see cref="Status"/>
|
||||
/// </summary>
|
||||
public required Status status { get; init; }
|
||||
}
|
||||
}
|
||||
|
||||
@ -4,32 +4,95 @@ using System.Text.Json;
|
||||
|
||||
namespace dopt.DeltaBarth
|
||||
{
|
||||
/// <summary>
|
||||
/// Spiegelung der internen Fehlertypen innerhalb der Python-Bibliothek
|
||||
/// </summary>
|
||||
public enum StatusCodes
|
||||
{
|
||||
/// <summary>
|
||||
/// erfolgreiche, fehlerfreie Durchführung der Routine
|
||||
/// </summary>
|
||||
[Description("Keine Fehler aufgetreten")]
|
||||
Erfolg = 0,
|
||||
/// <summary>
|
||||
/// Bei der API-Abfrage wurde der Timeout getriggert.
|
||||
/// </summary>
|
||||
[Description("Bei der Verbindung zum API-Server kam es zum Timeout")]
|
||||
VerbindungTimeout = 1,
|
||||
/// <summary>
|
||||
/// Bei der API-Abfrage ist ein unerwarteter Fehler aufgetreten, der unmittelbar die HTTP-Anfrage betrifft.
|
||||
/// </summary>
|
||||
[Description("Bei der Verbindung zum API-Server ist ein Fehler aufgetreten")]
|
||||
VerbindungFehler = 2,
|
||||
/// <summary>
|
||||
/// Der ausgewählte Datensatz enthält nicht genügend Datenpunkte.
|
||||
/// </summary>
|
||||
[Description("Der bereitgestellte Datensatz enthält in Summe zu wenige Einzeleinträge")]
|
||||
DatensatzZuWenigeDatenpunkte = 3,
|
||||
/// <summary>
|
||||
/// Der ausgewählte Datensatz enthält nach Aggregation pro Monat nicht genügend Datenpunkte.
|
||||
/// </summary>
|
||||
[Description("Der bereitgestellte Datensatz enthält nach Aggregation zu Monaten zu wenig Einträge")]
|
||||
DatensatzZuWenigeMonatsdatenpunkte = 4,
|
||||
[Description("Die Prognosequalität des Modells erfüllt nicht ide Mindestanforderungen")]
|
||||
/// <summary>
|
||||
/// Die Prognosequalität des Modells ist nicht zufriedenstellend. Eine verlässliche Prognose ist nicht möglich.
|
||||
/// </summary>
|
||||
[Description("Die Prognosequalität des Modells erfüllt nicht die Mindestanforderungen")]
|
||||
KeineVerlaesslichePrognose = 5,
|
||||
/// <summary>
|
||||
/// Es ist intern ein Fehler aufgetreten aufgetreten
|
||||
/// </summary>
|
||||
[Description("Interne Fehler, die während der Routine aufgetreten sind")]
|
||||
InternerFehler = 100,
|
||||
/// <summary>
|
||||
/// Es ist ein Fehler beim Schreiben der programminternen Datenbank aufgetreten.
|
||||
/// </summary>
|
||||
[Description("Interne Fehler, die während der Datenbankinteraktion aufgetreten sind")]
|
||||
InternerDbFehler = 150,
|
||||
/// <summary>
|
||||
/// Es ist ein Fehler auf dem API-Server aufgetreten.
|
||||
/// Das dazugehörige Status-Objekt sollte diesen Fehler zur Verfügung stellen können.
|
||||
/// <see cref="DataObjects.Status"/>
|
||||
/// <see cref="DataObjects.ApiServerError"/>
|
||||
/// </summary>
|
||||
[Description("Vom API-Server wurde eine Fehlermeldung zurückgegeben")]
|
||||
ApiServerFehler = 400,
|
||||
}
|
||||
/// <summary>
|
||||
/// Eine Exception, die genutzt wird, um anzuzeigen, dass beim Parsen der Python-Objekte
|
||||
/// ein Fehler aufgetreten ist.
|
||||
/// </summary>
|
||||
public class PythonParsingException : Exception
|
||||
{
|
||||
/// <summary>
|
||||
/// Konstruktor ohne Inhalt
|
||||
/// </summary>
|
||||
public PythonParsingException() { }
|
||||
/// <summary>
|
||||
/// Konstruktor mit Nachricht
|
||||
/// </summary>
|
||||
/// <param name="message"></param>
|
||||
public PythonParsingException(string message) : base(message) { }
|
||||
}
|
||||
/// <summary>
|
||||
/// Plugin-Klasse, mit der die Interaktion der zugrundeliegenden Python-Runtime erfolgt
|
||||
/// </summary>
|
||||
public class Plugin : SharpPython.BasePlugin
|
||||
{
|
||||
/// <summary>
|
||||
/// Python-interne Zustandsverwaltung
|
||||
/// </summary>
|
||||
protected dynamic pyModManagement;
|
||||
/// <summary>
|
||||
/// Python-interne Routinen und Pipelines
|
||||
/// </summary>
|
||||
protected dynamic pyModPipeline;
|
||||
/// <summary>
|
||||
/// Konstruktor der Plugin-Klasse.
|
||||
/// Kann mit beliebigem Pfad zu einer Python-Runtime initialisiert werden.
|
||||
/// </summary>
|
||||
/// <param name="runtimePath">Der Pfad zur Python-Runtime. Dieser muss zu dem Ordner zeigen,
|
||||
/// in welchem die Runtime in Form eines Ordners mit dem Namen "python" abliegt.</param>
|
||||
public Plugin(string runtimePath) : base(runtimePath: runtimePath, verbose: false)
|
||||
{
|
||||
base.Initialise();
|
||||
@ -39,12 +102,30 @@ namespace dopt.DeltaBarth
|
||||
pyModPipeline = Py.Import("delta_barth.pipelines");
|
||||
}
|
||||
}
|
||||
/// <summary>
|
||||
/// Initialisiert das Plugin mit allen relevanten Paramtern für die weitere Nutzung.
|
||||
/// Diese Methode sollte nur einmal je Instanz genutzt werden.
|
||||
/// </summary>
|
||||
/// <param name="datenPfad">Pfad zu einem Ordner, in dem Programmdaten ohne Bedenken dauerhaft abgelegt werden können.</param>
|
||||
/// <param name="basisApiUrl">Basis-URL zum Zugriff auf die API. Dies muss eine vollständige URL sein inkl. der Route "/api".</param>
|
||||
/// <param name="nutzername">Nutzername für die Datenbankanmeldung.</param>
|
||||
/// <param name="passwort">Passwort für die Datenbankanmeldung.</param>
|
||||
/// <param name="datenbank">Name der Datenbank, bei der die Anmeldung erfolgen soll.</param>
|
||||
/// <param name="mandant">Mandant für die Datenbankanmeldung.</param>
|
||||
public void Startup(string datenPfad, string basisApiUrl, string nutzername, string passwort, string datenbank, string mandant)
|
||||
{
|
||||
AssertNotDisposed();
|
||||
Setup(datenPfad, basisApiUrl);
|
||||
SetzeNutzerdaten(nutzername, passwort, datenbank, mandant);
|
||||
}
|
||||
/// <summary>
|
||||
/// Diese Methode erlaubt es, die relevanten Nutzerdaten zur Laufzeit des Plugins zu ändern.
|
||||
/// Dies beinhaltet: Nutzername, Passwort, Datenbankname, Mandant
|
||||
/// </summary>
|
||||
/// <param name="nutzername">Nutzername für die Datenbankanmeldung.</param>
|
||||
/// <param name="passwort">Passwort für die Datenbankanmeldung.</param>
|
||||
/// <param name="datenbank">Name der Datenbank, bei der die Anmeldung erfolgen soll.</param>
|
||||
/// <param name="mandant">Mandant für die Datenbankanmeldung.</param>
|
||||
public void SetzeNutzerdaten(string nutzername, string passwort, string datenbank, string mandant)
|
||||
{
|
||||
AssertNotDisposed();
|
||||
@ -52,6 +133,17 @@ namespace dopt.DeltaBarth
|
||||
pyModManagement.set_credentials(nutzername, passwort, datenbank, mandant);
|
||||
}
|
||||
}
|
||||
/// <summary>
|
||||
/// Ausführung der Umsatzprognose-Pipeline mit Dummy-Daten.
|
||||
/// Es werden keine API-Abrufe durchgeführt und somit auch keine Live-Daten genutzt.
|
||||
/// </summary>
|
||||
/// <param name="firmaId">optional: Firmen-ID, für die die Pipeline ausgeführt werden soll.
|
||||
/// Wird der Parameter nicht zur Verfügung gestellt, werden alle Firmen bzw. Kunden abgerufen</param>
|
||||
/// <param name="analyseBeginn">optional: Start-Datum, ab dem die Daten für die Erstellung des Prognosemodells genutzt werden.
|
||||
/// Daten, die weiter in der Vergangenheit liegen, werden nicht berücksichtigt.
|
||||
/// Wird der Parameter nicht zur Verfügung gestellt, wird die gesamte Historie genutzt.</param>
|
||||
/// <returns cref="DataObjects.UmsatzPrognoseAusgabe">Umsatzprognose inkl. Status-Objekt zur Nachvollziehbarkeit etwaig aufgetretener Fehler.</returns>
|
||||
/// <exception cref="PythonParsingException"></exception>
|
||||
public DataObjects.UmsatzPrognoseAusgabe UmsatzprognoseDummy(int? firmaId, DateTime? analyseBeginn)
|
||||
{
|
||||
AssertNotDisposed();
|
||||
@ -63,6 +155,18 @@ namespace dopt.DeltaBarth
|
||||
var parsed = JsonSerializer.Deserialize<DataObjects.UmsatzPrognoseAusgabe>(pyJson) ?? throw new PythonParsingException("Could not correctly parse object from Python");
|
||||
return parsed;
|
||||
}
|
||||
/// <summary>
|
||||
/// Ausführung der Umsatzprognose-Pipeline mit Live-Daten.
|
||||
/// Es werden API-Abrufe durchgeführt und somit auch Live-Daten genutzt.
|
||||
/// Hierfür muss sichergestellt sein, dass der API-Server erreichbar und abrufbereit ist.
|
||||
/// </summary>
|
||||
/// <param name="firmaId">optional: Firmen-ID, für die die Pipeline ausgeführt werden soll.
|
||||
/// Wird der Parameter nicht zur Verfügung gestellt, werden alle Firmen bzw. Kunden abgerufen</param>
|
||||
/// <param name="analyseBeginn">optional: Start-Datum, ab dem die Daten für die Erstellung des Prognosemodells genutzt werden.
|
||||
/// Daten, die weiter in der Vergangenheit liegen, werden nicht berücksichtigt.
|
||||
/// Wird der Parameter nicht zur Verfügung gestellt, wird die gesamte Historie genutzt.</param>
|
||||
/// <returns cref="DataObjects.UmsatzPrognoseAusgabe">Umsatzprognose inkl. Status-Objekt zur Nachvollziehbarkeit etwaig aufgetretener Fehler.</returns>
|
||||
/// <exception cref="PythonParsingException"></exception>
|
||||
public DataObjects.UmsatzPrognoseAusgabe Umsatzprognose(int? firmaId, DateTime? analyseBeginn)
|
||||
{
|
||||
AssertNotDisposed();
|
||||
@ -74,6 +178,11 @@ namespace dopt.DeltaBarth
|
||||
var parsed = JsonSerializer.Deserialize<DataObjects.UmsatzPrognoseAusgabe>(pyJson) ?? throw new PythonParsingException("Could not correctly parse object from Python");
|
||||
return parsed;
|
||||
}
|
||||
/// <summary>
|
||||
/// Setup der Python-internen Umgebung
|
||||
/// </summary>
|
||||
/// <param name="datenPfad">Pfad zu einem Ordner, in dem Programmdaten ohne Bedenken dauerhaft abgelegt werden können.</param>
|
||||
/// <param name="basisApiUrl">Basis-URL zum Zugriff auf die API. Dies muss eine vollständige URL sein inkl. der Route "/api".</param>
|
||||
protected void Setup(string datenPfad, string basisApiUrl)
|
||||
{
|
||||
AssertNotDisposed();
|
||||
@ -82,6 +191,10 @@ namespace dopt.DeltaBarth
|
||||
pyModManagement.setup(datenPfad, basisApiUrl);
|
||||
}
|
||||
}
|
||||
/// <summary>
|
||||
/// Hole die konfigurierte API-Basis-URL aus der Python-Umgebung
|
||||
/// </summary>
|
||||
/// <returns>konfigurierte Basis-URL</returns>
|
||||
protected string GetBaseApiUrl()
|
||||
{
|
||||
AssertNotDisposed();
|
||||
@ -92,6 +205,10 @@ namespace dopt.DeltaBarth
|
||||
}
|
||||
return pyJson;
|
||||
}
|
||||
/// <summary>
|
||||
/// Hole den konfigurierten Datenpfad zur Dateiverwaltung aus der Python-Umgebung
|
||||
/// </summary>
|
||||
/// <returns>konfigurierten Datenpfad</returns>
|
||||
protected string GetDataPath()
|
||||
{
|
||||
AssertNotDisposed();
|
||||
@ -102,6 +219,11 @@ namespace dopt.DeltaBarth
|
||||
}
|
||||
return pyJson;
|
||||
}
|
||||
/// <summary>
|
||||
/// Hole die konfigurierten Nutzerdaten zur API-Interaktion aus der Python-Umgebung
|
||||
/// </summary>
|
||||
/// <returns cref="DataObjects.Credentials">konfigurierte Nutzerdaten</returns>
|
||||
/// <exception cref="PythonParsingException"></exception>
|
||||
protected DataObjects.Credentials GetCredentials()
|
||||
{
|
||||
AssertNotDisposed();
|
||||
|
||||
@ -7,6 +7,7 @@
|
||||
<PlatformTarget>x64</PlatformTarget>
|
||||
<Platforms>x64</Platforms>
|
||||
<Version>0.3.3-dev1</Version>
|
||||
<GenerateDocumentationFile>True</GenerateDocumentationFile>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user