<?php

namespace App\Jobs;

use App\Models\EvaluationRun;
use App\Services\Evaluation\EvaluationCoordinator;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

/**
 * Job: StartEvaluationRunJob
 *
 * Odpovědnost:
 *  - Slouží jako ORCHESTRÁTOR vyhodnocovacího běhu (EvaluationRun).
 *  - Tento job NEPROVÁDÍ samotné vyhodnocení QSO ani výpočty bodů.
 *  - Je zodpovědný za bezpečné spuštění pipeline kroků vyhodnocení
 *    ve správném pořadí.
 *
 * Typický životní cyklus:
 *  1) Job je dispatchnut po kliknutí v administraci nebo backendovou akcí.
 *  2) Ověří, že EvaluationRun existuje a je ve stavu PENDING.
 *  3) Získá lock nad rozsahem dat (typicky round_id), aby zabránil
 *     souběžnému vyhodnocení stejných dat.
 *  4) Přepne EvaluationRun do stavu RUNNING a zapíše start běhu.
 *  5) Sestaví sekvenci (chain / batch) dílčích jobů:
 *       - příprava dat
 *       - parsing logů
 *       - matching QSO
 *       - výpočty skóre
 *       - agregace výsledků
 *       - finalizace a publikace
 *  6) Předá řízení jednotlivým krokům; tento job poté končí.
 *
 * Důležité zásady:
 *  - Tento job musí být IDEMPOTENTNÍ (opakované spuštění nesmí rozbít stav).
 *  - Nesmí obsahovat výpočetní logiku.
 *  - Nesmí zapisovat výsledky vyhodnocení.
 *  - Veškerá byznys logika patří do service layer a dílčích jobů.
 *
 * Queue:
 *  - Spouští se ve frontě "evaluation".
 *  - Používá se společně s ochranou proti souběhu (lock / WithoutOverlapping).
 */
class StartEvaluationRunJob implements ShouldQueue
{
    use Queueable;

    /**
     * Create a new job instance.
     */
    public function __construct(
        protected int $evaluationRunId
    )
    {
        //
    }

    /**
     * Spuštění vyhodnocovacího běhu.
     *
     * Metoda handle():
     *  - inicializuje vyhodnocovací běh
     *  - zajistí exkluzivitu nad daty
     *  - připraví a dispatchne navazující joby
     *
     * Poznámka:
     *  - Tato metoda by měla být krátká a čitelná.
     *  - Veškerá komplexní logika má být delegována
     *    do EvaluationCoordinator / service layer.
     */
    public function handle(): void
    {
        $run = EvaluationRun::find($this->evaluationRunId);
        if (! $run || $run->isCanceled()) {
            return;
        }

        app(EvaluationCoordinator::class)->start($run);
    }
}