Initial commit

app/Models/EvaluationRunEvent.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use App\Models\EvaluationRun;
+
+/**
+ * Model: EvaluationRunEvent
+ *
+ * Účel:
+ *  - Reprezentuje jednu auditní / diagnostickou událost vyhodnocovacího běhu
+ *    (EvaluationRun).
+ *  - Slouží k zaznamenávání průběhu vyhodnocovací pipeline pro účely:
+ *      - monitoringu v administraci
+ *      - diagnostiky chyb
+ *      - auditní stopy (co, kdy a v jakém kroku proběhlo)
+ *
+ * Kontext v architektuře:
+ *  - Události jsou vytvářeny během běhu background jobů
+ *    (PrepareRunJob, ParseLogJob, MatchQsoGroupJob, …, FinalizeRunJob).
+ *  - Jsou úzce svázány s jedním EvaluationRun a nikdy neexistují samostatně.
+ *
+ * Typické použití:
+ *  - Informování UI o aktuálním stavu a průběhu vyhodnocení.
+ *  - Záznam varování (např. nevalidní logy, ignorované QSO).
+ *  - Záznam chyb, které vedly k selhání kroku nebo celého běhu.
+ *
+ * Pole modelu:
+ *  - evaluation_run_id:
+ *      Reference na vyhodnocovací běh, ke kterému událost patří.
+ *  - level:
+ *      Úroveň události (např. info / warning / error / debug).
+ *  - message:
+ *      Lidsky čitelný popis události, vhodný pro zobrazení v UI.
+ *  - context:
+ *      Strukturovaná doplňující data (JSON), např.:
+ *        - identifikátory logů nebo QSO
+ *        - technické detaily chyby
+ *        - počty zpracovaných záznamů
+ *
+ * Co model NEDĚLÁ:
+ *  - neřídí stav EvaluationRun
+ *  - neobsahuje byznys logiku vyhodnocení
+ *  - neslouží jako systémový log (nahrazuje pouze audit pipeline)
+ *
+ * Zásady návrhu:
+ *  - Události mají být zapisovány sekvenčně během běhu pipeline.
+ *  - Neměly by se mazat ani přepisovat (append-only charakter).
+ *  - Slouží jako autoritativní zdroj informací o průběhu vyhodnocení.
+ */
+class EvaluationRunEvent extends Model
+{
+    protected $table = 'evaluation_run_events';
+
+    protected $fillable = [
+        'evaluation_run_id',
+        'level',
+        'message',
+        'context',
+    ];
+
+    protected $casts = [
+        'evaluation_run_id' => 'integer',
+        'context' => 'array',
+    ];
+
+    public function evaluationRun(): BelongsTo
+    {
+        return $this->belongsTo(EvaluationRun::class);
+    }
+}