feat(overtime-contingent) : contingent d'heures supplémentaires payées (#29)

## Résumé
Suivi par **année civile** (Janv–Déc) des heures supplémentaires payées des employés non-forfait (chauffeurs inclus) face au plafond légal (**350 h** chauffeurs / **220 h** autres).

- **Fiche employé** : encart header `Total H.payés {année} : X h / plafond h` (année civile courante, rouge si dépassement), via `GET /employees/{id}/overtime-contingent`.
- **Export PDF** `GET /overtime-contingent/print?year=&siteIds=` (ROLE_USER, périmètre `findScoped`) : groupé par site, colonnes Janv–Déc + colonne `Total payé / payable`. Drawer liste employés (année + sites).
- Heures payées = `base25 + base50` (hors majoration). Mapping exercice→civil : `mois ≥ 6 ? exercice−1 : exercice`.
- Cœur partagé pur `OvertimePaidContingentCalculator`.
- Ajout « Année civile » dans le titre des deux exports PDF (contingent H.supp. et heures de nuit).

## Tests
- 214 tests PHPUnit verts (calculateur : mapping civil, base-only, plafond ; builder : ventilation mensuelle, ligne à zéro).

## Hors périmètre (consigné)
- Bug latent `SalaryRecapPrintProvider` : rattachement des paiements RTT des mois Juin–Déc par année civile sur un stockage par exercice. À traiter séparément.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: #29
Co-authored-by: tristan <tristan@yuno.malio.fr>
Co-committed-by: tristan <tristan@yuno.malio.fr>

tests/Service/WorkHours/OvertimeContingentExportBuilderTest.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Service\WorkHours;
+
+use App\Entity\Employee;
+use App\Entity\EmployeeRttPayment;
+use App\Repository\EmployeeRttPaymentRepository;
+use App\Service\WorkHours\OvertimeContingentExportBuilder;
+use App\Service\WorkHours\OvertimePaidContingentCalculator;
+use PHPUnit\Framework\TestCase;
+use ReflectionProperty;
+
+/**
+ * @internal
+ */
+final class OvertimeContingentExportBuilderTest extends TestCase
+{
+    public function testBuildsRowsWithMonthlyTotalsAndCap(): void
+    {
+        // isDriver est résolu via le contrat courant : on le force par une
+        // sous-classe anonyme pour rester en test unitaire (sans BDD).
+        $driverEmp = new class extends Employee {
+            public function getIsDriver(): bool
+            {
+                return true;
+            }
+        };
+        $driverEmp->setLastName('Martin')->setFirstName('Luc');
+        $idRef = new ReflectionProperty(Employee::class, 'id');
+        $idRef->setValue($driverEmp, 7);
+
+        // Paiement : exercice 2027, mois 9 -> civil 2026, mois 9 ; base 100+20.
+        $payment = new EmployeeRttPayment()
+            ->setEmployee($driverEmp)
+            ->setYear(2027)->setMonth(9)
+            ->setBase25Minutes(100)->setBase50Minutes(20)
+        ;
+
+        $repo = $this->createStub(EmployeeRttPaymentRepository::class);
+        $repo->method('findByEmployeesAndYears')->willReturn([$payment]);
+
+        $builder = new OvertimeContingentExportBuilder($repo, new OvertimePaidContingentCalculator());
+
+        $rows = $builder->buildRows([$driverEmp], 2026);
+
+        self::assertCount(1, $rows);
+        self::assertSame(7, $rows[0]->employeeId);
+        self::assertSame('Martin Luc', $rows[0]->employeeName);
+        self::assertSame(120, $rows[0]->months[9]);
+        self::assertSame(0, $rows[0]->months[1]);
+        self::assertSame(120, $rows[0]->totalMinutes);
+        self::assertSame(350, $rows[0]->capHours); // chauffeur
+    }
+
+    public function testEmployeeWithNoPaymentsYieldsZeroRow(): void
+    {
+        $emp = new Employee();
+        $emp->setLastName('Durand')->setFirstName('Alice');
+        $idRef = new ReflectionProperty(Employee::class, 'id');
+        $idRef->setValue($emp, 99);
+
+        $repo = $this->createStub(EmployeeRttPaymentRepository::class);
+        $repo->method('findByEmployeesAndYears')->willReturn([]);
+
+        $builder = new OvertimeContingentExportBuilder($repo, new OvertimePaidContingentCalculator());
+        $rows    = $builder->buildRows([$emp], 2026);
+
+        self::assertCount(1, $rows);
+        self::assertSame(0, $rows[0]->totalMinutes);
+        self::assertSame(0, $rows[0]->months[6]);
+        self::assertSame(220, $rows[0]->capHours); // non-driver
+    }
+}

tests/Service/WorkHours/OvertimePaidContingentCalculatorTest.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Service\WorkHours;
+
+use App\Entity\EmployeeRttPayment;
+use App\Service\WorkHours\OvertimePaidContingentCalculator;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+final class OvertimePaidContingentCalculatorTest extends TestCase
+{
+    public function testMapsPaymentToCalendarYearAndSumsBaseOnly(): void
+    {
+        $calc = new OvertimePaidContingentCalculator();
+
+        // Septembre 2025 stocké en exercice 2026 (mois 9 >= 6 -> civil 2025).
+        // Mars 2026 stocké en exercice 2026 (mois 3 < 6 -> civil 2026).
+        // Septembre 2026 stocké en exercice 2027 (mois 9 >= 6 -> civil 2026).
+        // March 2026 payment has a large bonus (999 min) that must be excluded.
+        $payments = [
+            $this->payment(2026, 9, 120, 0),         // civil 2025 -> exclu de 2026
+            $this->payment(2026, 3, 60, 30, 999),    // civil 2026 -> mois 3, bonus ignoré
+            $this->payment(2027, 9, 100, 20),        // civil 2026 -> mois 9
+        ];
+
+        $months = $calc->monthlyBaseMinutes($payments, 2026);
+
+        self::assertSame(90, $months[3]);   // 60 + 30 (bonus 999 excluded)
+        self::assertSame(120, $months[9]);  // 100 + 20
+        self::assertSame(0, $months[1]);
+        self::assertSame(0, $months[8]);
+        self::assertSame(210, $calc->totalBaseMinutes($payments, 2026)); // bonus ignoré
+    }
+
+    public function testMonth5BelongsToExerciseYearAndMonth6ToPreviousCalendarYear(): void
+    {
+        $calc = new OvertimePaidContingentCalculator();
+
+        $payments = [
+            $this->payment(2026, 5, 50, 0),  // mai -> civil 2026
+            $this->payment(2026, 6, 70, 0),  // juin -> civil 2025
+        ];
+
+        self::assertSame(50, $calc->totalBaseMinutes($payments, 2026));
+        self::assertSame(70, $calc->totalBaseMinutes($payments, 2025));
+    }
+
+    public function testCapHours(): void
+    {
+        $calc = new OvertimePaidContingentCalculator();
+
+        self::assertSame(350, $calc->capHours(true));
+        self::assertSame(220, $calc->capHours(false));
+    }
+
+    public function testEmptyPaymentsYieldsZeros(): void
+    {
+        $calc   = new OvertimePaidContingentCalculator();
+        $months = $calc->monthlyBaseMinutes([], 2026);
+
+        self::assertSame(0, $months[1]);
+        self::assertSame(0, $months[12]);
+        self::assertSame(0, array_sum($months));
+        self::assertSame(0, $calc->totalBaseMinutes([], 2026));
+    }
+
+    private function payment(
+        int $exerciseYear,
+        int $month,
+        int $base25,
+        int $base50,
+        int $bonus25 = 0,
+        int $bonus50 = 0,
+    ): EmployeeRttPayment {
+        return new EmployeeRttPayment()
+            ->setYear($exerciseYear)
+            ->setMonth($month)
+            ->setBase25Minutes($base25)
+            ->setBase50Minutes($base50)
+            ->setBonus25Minutes($bonus25)
+            ->setBonus50Minutes($bonus50)
+        ;
+    }
+}