Initial commit

app/Jobs/StartEvaluationRunJob.php

@@ -0,0 +1,80 @@
+<?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);
+    }
+}