GlossariumReporter API

Übersicht

Die GlossariumReporter API ist die zentrale Service-Klasse für alle Glossarium-Reports in Hermeneus. Sie ermöglicht das systematische Erfassen, Verwalten und Abfragen von Berichten über Glossar-Einträge aus drei verschiedenen Quellen: System-Events, User-Feedback und automatische Daemon-Validierung.

Dateipfad: app/ServiceClasses/Glossarium/GlossariumReporter.phpModel: App\Models\GlossariumDaemonReportDatenbanktabelle: glossarium__daemon_reports

Die drei Report-Kanäle

1. Event-Reports (System)

Event-Reports werden automatisch vom System erstellt, wenn bestimmte Ereignisse eintreten:

• Vokabel nicht gefunden bei der Textanalyse
• Morphologisierung fehlgeschlagen
• Import-Probleme
• API-Fehler beim Abrufen von Vokabeln

Verwendungsbeispiel:

use App\ServiceClasses\Glossarium\GlossariumReporter;

// Einfacher Event-Report ohne Vocab-Model
GlossariumReporter::reportEvent(
    'not_found',                    // Report-Typ
    null,                           // Vocab-Model (optional)
    'Vokabel nicht im Glossar gefunden', // Nachricht
    ['headword' => 'arma', 'source' => 'TextAnalyzer'] // Metadata
);

// Event-Report mit Vocab-Model
GlossariumReporter::reportEvent(
    'morph_error',
    $vocab,
    'Morphologisierung fehlgeschlagen: Unbekannte Konjugation',
    ['attempted_form' => 'armatus']
);

Wichtig: Identische Event-Reports (gleicher Headword, Typ, Source und Message) werden nicht doppelt angelegt, sondern ihr count-Feld wird hochgezählt.

2. User-Reports (Manuelles Feedback)

User-Reports erfassen Feedback von Benutzern:

• Bedeutungsvorschläge
• Fehlermeldungen zu Einträgen
• Korrekturwünsche
• Verbesserungsvorschläge

Verwendungsbeispiel:

use App\ServiceClasses\Glossarium\GlossariumReporter;

// Bedeutungsvorschlag eines Users
GlossariumReporter::reportFromUser(
    $vocab,                               // Vocab-Model (required)
    'bedeutung_suggestion',               // Report-Typ
    'Die Bedeutung "Krieg" fehlt hier',   // Nachricht des Users
    auth()->user()->id                    // User-ID
);

// Fehlermeldung
GlossariumReporter::reportFromUser(
    $vocab,
    'error_report',
    'Genus ist falsch angegeben - sollte Neutrum sein',
    $userId
);

3. Daemon-Reports (Automatische Validierung)

Daemon-Reports werden durch Varro (GlossariumDaemon) bei automatischer Validierung erstellt:

• wortart_error - Falsche Wortart erkannt (nicht konvertierbar)
• duplicate - Duplikat erkannt
• validation_issue - Sonstige Validierungsprobleme

Verwendungsbeispiele:

use App\ServiceClasses\Glossarium\GlossariumReporter;

// Allgemeine Daemon-Report-Erstellung
GlossariumReporter::reportFromDaemon(
    'validation_issue',         // Report-Typ
    $vocab,                     // Vocab-Model
    $issues,                    // Issues-Array aus Varro
    'Optionale Nachricht'
);

// Kurzform für wortart_error (häufigster Fall)
GlossariumReporter::reportWortartError($vocab, $issues);

// Entspricht:
GlossariumReporter::reportFromDaemon(
    'wortart_error',
    $vocab,
    $issues
);

Anwendungsfall: Ein Nomen-Eintrag wird von Varro als Verb identifiziert. Da die Konvertierung nur für Nomen zu Eigenname erlaubt ist, wird der Eintrag gelöscht und ein wortart_error-Report erstellt.

Abfrage-Methoden

Alle Reports abrufen

// Alle Reports
$allReports = GlossariumReporter::get();

// Gefiltert nach Typ
$wortartErrors = GlossariumReporter::get('wortart_error');
$duplicates = GlossariumReporter::get('duplicate');

Pending Reports

// Alle pending Reports
$pending = GlossariumReporter::getPending();

// Gefiltert nach Source
$pendingDaemonReports = GlossariumReporter::getPending('daemon');
$pendingUserReports = GlossariumReporter::getPending('user');
$pendingEventReports = GlossariumReporter::getPending('event');

Spezifische Report-Typen

// Alle wortart_error Reports
$wortartErrors = GlossariumReporter::getWortartErrors();

Statistiken

$stats = GlossariumReporter::getStatistics();

/* Rückgabe:
[
    'total' => 123,
    'pending' => 45,
    'by_source' => [
        'event' => 20,
        'user' => 15,
        'daemon' => 88,
    ],
    'wortart_errors' => 12,
]
*/

Verwaltungsmethoden

Report als bearbeitet markieren

// Mögliche Status: 'deleted', 'reviewed', 'restored', 'pending'
$report = GlossariumReporter::markAsProcessed($reportId, 'reviewed');

// Setzt auch 'processed_at' Timestamp

Report löschen

$success = GlossariumReporter::delete($reportId);
// Gibt true/false zurück

Das GlossariumDaemonReport Model

Für direkten Zugriff auf die Reports kann auch das Model verwendet werden:

Verfügbare Scopes

use App\Models\GlossariumDaemonReport;

// Pending Reports
$pending = GlossariumDaemonReport::pending()->get();

// Wortart-Error Reports
$wortartErrors = GlossariumDaemonReport::wortartErrors()->get();

// Nach Source filtern
$daemonReports = GlossariumDaemonReport::bySource('daemon')->get();
$userReports = GlossariumDaemonReport::bySource('user')->get();

// Daemon-Reports (Kurzform für bySource('daemon'))
$daemonReports = GlossariumDaemonReport::daemonReports()->get();

// Nach Wortart filtern
$nomenReports = GlossariumDaemonReport::forWortart('nomen')->get();

Scope-Kombinationen

// Pending Daemon-Reports für Verben
$reports = GlossariumDaemonReport::pending()
    ->daemonReports()
    ->forWortart('verbum')
    ->orderBy('created_at', 'desc')
    ->get();

// Wortart-Errors mit hoher Priorität
$criticalErrors = GlossariumDaemonReport::wortartErrors()
    ->pending()
    ->where('created_at', '>', now()->subDays(7))
    ->get();

Factory-Methoden des Models

// Wortart-Error Report erstellen
$report = GlossariumDaemonReport::createFromWortartError($vocab, $issues);

// Event-Report erstellen
$report = GlossariumDaemonReport::createFromEvent(
    $type,
    $vocab,
    $message,
    $metadata
);

// User-Report erstellen
$report = GlossariumDaemonReport::createFromUser(
    $vocab,
    $type,
    $message,
    $userId
);

Datenbank-Struktur

Die Reports werden in der Tabelle glossarium__daemon_reports gespeichert:

Wichtige Felder

Feld	Typ	Beschreibung
headword	string	Das betroffene Lemma (z.B. "arma")
wortart	string	Die Wortart des Eintrags
type	string	Report-Typ (wortart_error, duplicate, etc.)
source	enum	Quelle: event, user, daemon
reportable_type	string	Polymorphe Relation - Model-Klasse
reportable_id	integer	Polymorphe Relation - Model-ID
vocab_data	json	Snapshot des Vocab-Eintrags zum Zeitpunkt
issues_found	json	Array mit erkannten Issues (von Varro)
message	text	Beschreibung / Nachricht
user_id	integer	Bei User-Reports: ID des meldenden Users
status	enum	pending, deleted, reviewed, restored
processed_at	timestamp	Wann der Report bearbeitet wurde
count	integer	Anzahl identischer Event-Reports

Polymorphe Relation

Die Tabelle nutzt eine polymorphe Relation (reportable_type, reportable_id) für die Verknüpfung mit Vocab-Models:

// Im Model
public function reportable(): MorphTo
{
    return $this->morphTo();
}

// Verwendung
$vocab = $report->reportable; // Gibt das zugehörige Vocab-Model zurück

Konstanten

Report-Sources

GlossariumDaemonReport::SOURCE_EVENT   // 'event'
GlossariumDaemonReport::SOURCE_USER    // 'user'
GlossariumDaemonReport::SOURCE_DAEMON  // 'daemon'

Report-Types (Daemon)

GlossariumDaemonReport::TYPE_WORTART_ERROR      // 'wortart_error'
GlossariumDaemonReport::TYPE_DUPLICATE          // 'duplicate'
GlossariumDaemonReport::TYPE_VALIDATION_ISSUE   // 'validation_issue'

Report-Status

GlossariumDaemonReport::STATUS_PENDING   // 'pending'
GlossariumDaemonReport::STATUS_DELETED   // 'deleted'
GlossariumDaemonReport::STATUS_REVIEWED  // 'reviewed'
GlossariumDaemonReport::STATUS_RESTORED  // 'restored'

Accessors

username

Der username-Accessor gibt den Benutzernamen des meldenden Users zurück (bei User-Reports):

$report = GlossariumDaemonReport::find($id);
echo $report->username; // Automatisch aus user-Relation geladen

detected_wortart

Der detected_wortart-Accessor extrahiert die von Varro erkannte Ziel-Wortart aus issues_found:

$report = GlossariumDaemonReport::wortartErrors()->first();
echo $report->detected_wortart; // z.B. "verbum"

// Nützlich für:
// "Nomen 'arma' wurde als Verbum erkannt"
echo "Eintrag '{$report->headword}' ({$report->wortart}) wurde als {$report->detected_wortart} erkannt";

Integration mit GlossariumDaemon

Der GlossariumDaemon erstellt automatisch Reports in bestimmten Situationen:

Automatische Report-Erstellung bei delete-Action

Wenn eine Suggestion mit recommended_action = 'delete' durch einen wortart_error gerechtfertigt ist, wird automatisch ein Report erstellt:

// In GlossariumDaemonService::adjustRecommendedAction()
if ($adjustedAction === 'delete') {
    $this->createWortartErrorReport($vocab, $issuesWithConfirmed);
}

// createWortartErrorReport() ruft auf:
GlossariumReporter::reportWortartError($vocab, $allIssues);

Verwendung in VarroValidator

// Nach erfolgreicher Validierung mit wortart_error
if ($hasWortartError && !$isConvertible) {
    // Erstelle Report für nicht-konvertierbare Wortart-Fehler
    GlossariumReporter::reportFromDaemon(
        'wortart_error',
        $vocab,
        $issues,
        "Eintrag konnte nicht konvertiert werden"
    );
}

Best Practices

1. Event-Reports sparsam verwenden

Event-Reports sollten nur für wirklich wichtige System-Ereignisse verwendet werden, nicht für normale Programmfluss-Informationen.

// GUT: Wichtiges Event
GlossariumReporter::reportEvent('import_failed', null, 'CSV-Import abgebrochen', [
    'file' => $filename,
    'error' => $exception->getMessage()
]);

// SCHLECHT: Zu detailliert
GlossariumReporter::reportEvent('vocab_accessed', $vocab, 'Vokabel wurde abgerufen');

2. User-Reports validieren

Vor der Erstellung von User-Reports sollte die Eingabe validiert werden:

// Validierung
$validated = $request->validate([
    'message' => 'required|string|max:500',
    'type' => 'required|in:bedeutung_suggestion,error_report,correction',
]);

// Dann Report erstellen
GlossariumReporter::reportFromUser(
    $vocab,
    $validated['type'],
    $validated['message'],
    auth()->id()
);

3. Daemon-Reports mit vollständigen Issues

Daemon-Reports sollten immer das vollständige Issues-Array aus Varro enthalten:

// GUT: Vollständige Issues
GlossariumReporter::reportWortartError($vocab, $allIssues);

// SCHLECHT: Nur Teil der Information
GlossariumReporter::reportWortartError($vocab, []);

4. Status-Updates dokumentieren

Bei Änderung des Report-Status sollte dokumentiert werden, warum:

// Status-Update mit Logging
Log::info("Report {$reportId} wird als 'reviewed' markiert: Admin-Entscheidung nach manueller Prüfung");
GlossariumReporter::markAsProcessed($reportId, 'reviewed');

Häufige Anwendungsfälle

Überwachung der Glossar-Qualität

// Dashboard-Statistiken
$stats = GlossariumReporter::getStatistics();

// Kritische Issues zuerst
$critical = GlossariumDaemonReport::wortartErrors()
    ->pending()
    ->orderBy('created_at', 'desc')
    ->limit(10)
    ->get();

// User-Feedback auswerten
$userSuggestions = GlossariumDaemonReport::bySource('user')
    ->where('type', 'bedeutung_suggestion')
    ->pending()
    ->get();

Batch-Verarbeitung von Reports

// Alle pending Daemon-Reports verarbeiten
$pending = GlossariumReporter::getPending('daemon');

foreach ($pending as $report) {
    // Automatische Verarbeitung basierend auf Typ
    if ($report->type === 'wortart_error') {
        // Vocab löschen falls noch vorhanden
        $vocab = $report->reportable;
        if ($vocab && !$vocab->trashed()) {
            $vocab->delete();
        }
        GlossariumReporter::markAsProcessed($report->id, 'reviewed');
    }
}

Debugging von Varro-Ergebnissen

// Finde alle Nomen die als Verben erkannt wurden
$nomenToVerb = GlossariumDaemonReport::wortartErrors()
    ->forWortart('nomen')
    ->get()
    ->filter(function($report) {
        return $report->detected_wortart === 'verbum';
    });

// Analysiere die Issues
foreach ($nomenToVerb as $report) {
    dump([
        'lemma' => $report->headword,
        'issues' => $report->issues_found,
        'vocab_snapshot' => $report->vocab_data,
    ]);
}

Verwandte Dokumentation

• GlossariumDaemon: Automatische Validierung von Glossar-Einträgen
• Varro Service: KI-basierte Validierung und Qualitätskontrolle
• Vocab-Models: Die verschiedenen Wortart-Models (Nomen, Verb, etc.)
• Morphologie-System: Wie Vokabeln morphologisiert werden

Changelog

• 2025-12-14: Initiale Dokumentation erstellt
  • Alle drei Report-Kanäle dokumentiert
  • Model-Scopes und Factory-Methoden beschrieben
  • Best Practices und Anwendungsfälle hinzugefügt