<?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);
    }
}