Initial commit

app/Http/Requests/StartEvaluationRunRequest.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * Request: StartEvaluationRunRequest
+ *
+ * Účel:
+ *  - HTTP request objekt pro spuštění vyhodnocovacího běhu (EvaluationRun).
+ *  - Slouží k validaci a autorizaci vstupních dat při inicializaci vyhodnocení
+ *    z administrace (React SPA) nebo interní backendové akce.
+ *
+ * Kontext v architektuře:
+ *  - Používá se v EvaluationRunController při volání endpointu typu:
+ *      POST /api/rounds/{round}/evaluation-runs
+ *  - Je první validační vrstvou před vytvořením EvaluationRun záznamu
+ *    a před dispatchnutím StartEvaluationRunJob.
+ *
+ * Odpovědnosti requestu:
+ *  - Ověřit, že požadavek přichází od autorizovaného uživatele
+ *    (typicky administrátor nebo oprávněná role).
+ *  - Validovat vstupní parametry potřebné ke spuštění vyhodnocení,
+ *    např.:
+ *      - typ vyhodnocení (test / official)
+ *      - identifikace rule setu
+ *      - volitelný scope (bandy, kategorie, power kategorie)
+ *      - případné volby override (pokud jsou povoleny)
+ *
+ * Co request NEDĚLÁ:
+ *  - nespouští vyhodnocení
+ *  - neobsahuje byznys logiku
+ *  - nemění stav databáze
+ *
+ * Zásady návrhu:
+ *  - Autorizace a validace musí být striktní,
+ *    protože spuštění vyhodnocení je nákladná operace.
+ *  - Request má zůstat jednoduchý a čitelný;
+ *    komplexní logika patří do controlleru nebo service layer.
+ */
+class StartEvaluationRunRequest extends FormRequest
+{
+    /**
+     * Určuje, zda má aktuální uživatel oprávnění spustit vyhodnocovací běh.
+     *
+     * Typicky:
+     *  - pouze administrátor
+     *  - nebo uživatel s explicitním oprávněním ke správě závodu/kola
+     *
+     * Poznámka:
+     *  - Implementace má delegovat rozhodnutí na Policy nebo Gate.
+     */
+    public function authorize(): bool
+    {
+        return false;
+    }
+
+    /**
+     * Validační pravidla pro spuštění vyhodnocení.
+     *
+     * Metoda definuje strukturu a povolené hodnoty vstupních dat,
+     * která ovlivňují průběh vyhodnocovací pipeline.
+     *
+     * Poznámka:
+     *  - Konkrétní validační pravidla budou záviset
+     *    na požadavcích UI a pravidlech soutěže.
+     *  - Typicky se zde validují pouze technické parametry,
+     *    nikoli existence nebo stav doménových entit.
+     */
+    public function rules(): array
+    {
+        return [
+            //
+        ];
+    }
+}