feat(heures) : export Contingent heures de nuit (liste employés) (#28)

## Résumé
Nouvel export PDF **Contingent heures de nuit** dans le drawer Export de la liste employés.

- PDF **A4 paysage** : lignes = employés (groupés par site, triés displayOrder/nom/prénom), colonnes = 12 mois civils, chaque mois avec 2 sous-colonnes **H.nuit** et **N.jours**.
- Heures de nuit = minutes dans la fenêtre **21h→6h** via un service partagé `NightHoursCalculator` (mutualisé avec `WorkHourWeeklySummaryProvider` et `YearlyHoursExportBuilder` — duplication supprimée, sans changement de comportement).
- **Conducteurs inclus** via `WorkHour.nightHoursMinutes`. Statut conducteur résolu par date.
- **N.jours** = nb de jours où les minutes de nuit ≥ 240 (4h). Aucun crédit absence/férié.
- Périmètre via `EmployeeRepository::findScoped` (admin → tous, chef de site → ses sites), endpoint `GET /night-hours-contingent/print?year=YYYY` (`ROLE_USER`).
- Sélecteur d'année (année civile). Colonne Nom calibrée, séparateurs de mois épais.

## Composants
- Service `NightHoursCalculator`, builder `NightContingentExportBuilder`, DTO `NightContingentRow`
- Provider `NightHoursContingentPrintProvider` + opération API `NightHoursContingentPrint`
- Gabarit `templates/night-hours-contingent/print.html.twig`
- Option frontend dans `frontend/pages/employees/index.vue`
- Docs : `doc/functional-rules.md`, `CLAUDE.md`, `frontend/data/documentation-content.ts`

## Tests
- Nouveaux tests unitaires : `NightHoursCalculatorTest` (fenêtre 21h→6h, passage minuit, bornes), `NightContingentExportBuilderTest` (agrégation mensuelle, règle ≥4h=1j, conducteur, cas sans heures)
- Suite complète : **208 tests OK**
- Rendu PDF validé visuellement (Twig→Dompdf)

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

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

src/Service/Rtt/RttRecoveryComputationService.php

@@ -18,6 +18,7 @@ use App\Service\Contracts\EmployeeContractResolver;
 use App\Service\WorkHours\AbsenceSegmentsResolver;
 use App\Service\WorkHours\DailyReferenceMinutesResolver;
 use App\Service\WorkHours\HolidayVirtualHoursResolver;
+use App\Service\WorkHours\NightHoursCalculator;
 use App\Service\WorkHours\WorkedHoursCreditPolicy;
 use DateTimeImmutable;
 
@@ -34,6 +35,7 @@ final readonly class RttRecoveryComputationService
         private DailyReferenceMinutesResolver $dailyReferenceResolver,
         private HolidayVirtualHoursResolver $holidayVirtualHoursResolver,
         private SolidarityDayResolver $solidarityDayResolver,
+        private NightHoursCalculator $nightHoursCalculator,
         string $rttStartDate = '',
     ) {
         $this->rttStartDate = '' !== $rttStartDate ? new DateTimeImmutable($rttStartDate) : null;
@@ -359,13 +361,12 @@ final readonly class RttRecoveryComputationService
         ];
 
         $totalMinutes = 0;
-        $nightMinutes = 0;
         foreach ($ranges as [$from, $to]) {
             $totalMinutes += $this->intervalMinutes($from, $to);
-            $nightMinutes += $this->nightIntervalMinutes($from, $to);
         }
 
-        $dayMinutes = max(0, $totalMinutes - $nightMinutes);
+        $nightMinutes = $this->nightHoursCalculator->nightMinutesFromRanges($workHour);
+        $dayMinutes   = max(0, $totalMinutes - $nightMinutes);
 
         return new WorkMetrics(
             dayMinutes: $dayMinutes,
@@ -411,35 +412,6 @@ final readonly class RttRecoveryComputationService
         return max(0, $end - $start);
     }
 
-    private function nightIntervalMinutes(?string $from, ?string $to): int
-    {
-        $interval = $this->resolveInterval($from, $to);
-        if (null === $interval) {
-            return 0;
-        }
-
-        [$start, $end] = $interval;
-        $windows       = [[0, 360], [1260, 1440]];
-        $total         = 0;
-
-        for ($dayOffset = 0; $dayOffset <= 1; ++$dayOffset) {
-            $shift = $dayOffset * 1440;
-            foreach ($windows as [$windowStart, $windowEnd]) {
-                $total += $this->overlap($start, $end, $windowStart + $shift, $windowEnd + $shift);
-            }
-        }
-
-        return $total;
-    }
-
-    private function overlap(int $startA, int $endA, int $startB, int $endB): int
-    {
-        $start = max($startA, $startB);
-        $end   = min($endA, $endB);
-
-        return max(0, $end - $start);
-    }
-
     /**
      * @param list<string>             $days
      * @param array<string, ?Contract> $contractsByDate

src/Service/WorkHours/NightContingentExportBuilder.php

@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service\WorkHours;
+
+use App\Dto\WorkHours\NightContingentRow;
+use App\Entity\Employee;
+use App\Repository\Contract\WorkHourReadRepositoryInterface;
+use App\Service\Contracts\EmployeeContractResolver;
+use DateTimeImmutable;
+
+/**
+ * Construit, par employe, les totaux mensuels d'heures de nuit et le nombre de
+ * nuits travaillees (>= 4h de nuit dans la journee). Fenetre 21h->6h via
+ * NightHoursCalculator. Conducteurs : minutes saisies (nightHoursMinutes).
+ * Aucun credit absence/ferie : seules les heures reellement travaillees comptent.
+ */
+final readonly class NightContingentExportBuilder
+{
+    private const int NIGHT_DAY_THRESHOLD_MINUTES = 240;
+
+    public function __construct(
+        private WorkHourReadRepositoryInterface $workHourRepository,
+        private EmployeeContractResolver $contractResolver,
+        private NightHoursCalculator $nightHoursCalculator,
+    ) {}
+
+    /**
+     * @param list<Employee> $employees
+     *
+     * @return list<NightContingentRow>
+     */
+    public function buildRows(array $employees, int $year): array
+    {
+        $from = new DateTimeImmutable(sprintf('%d-01-01', $year));
+        $to   = new DateTimeImmutable(sprintf('%d-12-31', $year));
+
+        $workHours = $this->workHourRepository->findByDateRangeAndEmployees($from, $to, $employees);
+
+        $byEmployee = [];
+        foreach ($workHours as $wh) {
+            $employeeId = $wh->getEmployee()?->getId();
+            if (null === $employeeId) {
+                continue;
+            }
+            $byEmployee[$employeeId][] = $wh;
+        }
+
+        $days = [];
+        foreach ($workHours as $wh) {
+            $days[$wh->getWorkDate()->format('Y-m-d')] = true;
+        }
+        $days = array_keys($days);
+
+        $driverMap = $this->contractResolver->resolveIsDriverForEmployeesAndDays($employees, $days);
+
+        $rows = [];
+        foreach ($employees as $employee) {
+            $employeeId = $employee->getId();
+            if (null === $employeeId) {
+                continue;
+            }
+
+            $months = [];
+            for ($m = 1; $m <= 12; ++$m) {
+                $months[$m] = ['nightMinutes' => 0, 'nightDays' => 0];
+            }
+
+            foreach ($byEmployee[$employeeId] ?? [] as $wh) {
+                $date     = DateTimeImmutable::createFromInterface($wh->getWorkDate());
+                $ymd      = $date->format('Y-m-d');
+                $isDriver = $driverMap[$employeeId][$ymd] ?? false;
+                $nightMin = $this->nightHoursCalculator->nightMinutesForWorkHour($wh, $isDriver);
+                if ($nightMin <= 0) {
+                    continue;
+                }
+
+                $month = (int) $date->format('n');
+                $months[$month]['nightMinutes'] += $nightMin;
+                if ($nightMin >= self::NIGHT_DAY_THRESHOLD_MINUTES) {
+                    ++$months[$month]['nightDays'];
+                }
+            }
+
+            $rows[] = new NightContingentRow(
+                employeeId: $employeeId,
+                employeeName: trim($employee->getLastName().' '.$employee->getFirstName()),
+                months: $months,
+            );
+        }
+
+        return $rows;
+    }
+}

src/Service/WorkHours/NightHoursCalculator.php

@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service\WorkHours;
+
+use App\Entity\WorkHour;
+
+/**
+ * Calcul des minutes travaillees de nuit (fenetre 21h->6h).
+ *
+ * Fenetres en minutes depuis 00:00 : [0,360] (00:00-06:00) et [1260,1440]
+ * (21:00-24:00). On projette sur J+1 pour les shifts qui traversent minuit.
+ * Source de verite unique partagee par les ecrans Heures et les exports.
+ */
+final readonly class NightHoursCalculator
+{
+    /**
+     * Minutes de nuit d'un WorkHour. Conducteurs : champ manuel nightHoursMinutes.
+     * Non-conducteurs : somme calculee depuis les plages matin/apres-midi/soir.
+     */
+    public function nightMinutesForWorkHour(WorkHour $workHour, bool $isDriver): int
+    {
+        if ($isDriver) {
+            return $workHour->getNightHoursMinutes() ?? 0;
+        }
+
+        return $this->nightMinutesFromRanges($workHour);
+    }
+
+    public function nightMinutesFromRanges(WorkHour $workHour): int
+    {
+        $ranges = [
+            [$workHour->getMorningFrom(), $workHour->getMorningTo()],
+            [$workHour->getAfternoonFrom(), $workHour->getAfternoonTo()],
+            [$workHour->getEveningFrom(), $workHour->getEveningTo()],
+        ];
+
+        $total = 0;
+        foreach ($ranges as [$from, $to]) {
+            $total += $this->nightIntervalMinutes($from, $to);
+        }
+
+        return $total;
+    }
+
+    public function nightIntervalMinutes(?string $from, ?string $to): int
+    {
+        $interval = $this->resolveInterval($from, $to);
+        if (null === $interval) {
+            return 0;
+        }
+
+        [$start, $end] = $interval;
+        $windows       = [[0, 360], [1260, 1440]];
+        $total         = 0;
+
+        for ($dayOffset = 0; $dayOffset <= 1; ++$dayOffset) {
+            $shift = $dayOffset * 1440;
+            foreach ($windows as [$windowStart, $windowEnd]) {
+                $total += $this->overlap($start, $end, $windowStart + $shift, $windowEnd + $shift);
+            }
+        }
+
+        return $total;
+    }
+
+    /**
+     * @return null|array{int, int}
+     */
+    private function resolveInterval(?string $from, ?string $to): ?array
+    {
+        $fromMinutes = $this->toMinutes($from);
+        $toMinutes   = $this->toMinutes($to);
+        if (null === $fromMinutes || null === $toMinutes) {
+            return null;
+        }
+
+        $end = $toMinutes <= $fromMinutes ? $toMinutes + 1440 : $toMinutes;
+
+        return [$fromMinutes, $end];
+    }
+
+    private function toMinutes(?string $time): ?int
+    {
+        if (null === $time || '' === $time) {
+            return null;
+        }
+
+        [$hours, $minutes] = array_map('intval', explode(':', $time));
+
+        return ($hours * 60) + $minutes;
+    }
+
+    private function overlap(int $startA, int $endA, int $startB, int $endB): int
+    {
+        $start = max($startA, $startB);
+        $end   = min($endA, $endB);
+
+        return max(0, $end - $start);
+    }
+}

src/Service/WorkHours/YearlyHoursExportBuilder.php

@@ -29,6 +29,7 @@ class YearlyHoursExportBuilder
         private WorkedHoursCreditPolicy $workedHoursCreditPolicy,
         private PublicHolidayServiceInterface $publicHolidayService,
         private HolidayVirtualHoursResolver $holidayVirtualHoursResolver,
+        private NightHoursCalculator $nightHoursCalculator,
     ) {}
 
     /**
@@ -541,14 +542,12 @@ class YearlyHoursExportBuilder
         ];
 
         $totalMinutes = 0;
-        $nightMinutes = 0;
-
         foreach ($ranges as [$from, $to]) {
             $totalMinutes += $this->intervalMinutes($from, $to);
-            $nightMinutes += $this->nightIntervalMinutes($from, $to);
         }
 
-        $dayMinutes = max(0, $totalMinutes - $nightMinutes);
+        $nightMinutes = $this->nightHoursCalculator->nightMinutesFromRanges($workHour);
+        $dayMinutes   = max(0, $totalMinutes - $nightMinutes);
 
         return new WorkMetrics(
             dayMinutes: $dayMinutes,
@@ -596,35 +595,6 @@ class YearlyHoursExportBuilder
         return max(0, $end - $start);
     }
 
-    private function nightIntervalMinutes(?string $from, ?string $to): int
-    {
-        $interval = $this->resolveInterval($from, $to);
-        if (null === $interval) {
-            return 0;
-        }
-
-        [$start, $end] = $interval;
-        $windows       = [[0, 360], [1260, 1440]];
-        $total         = 0;
-
-        for ($dayOffset = 0; $dayOffset <= 1; ++$dayOffset) {
-            $shift = $dayOffset * 1440;
-            foreach ($windows as [$windowStart, $windowEnd]) {
-                $total += $this->overlap($start, $end, $windowStart + $shift, $windowEnd + $shift);
-            }
-        }
-
-        return $total;
-    }
-
-    private function overlap(int $startA, int $endA, int $startB, int $endB): int
-    {
-        $start = max($startA, $startB);
-        $end   = min($endA, $endB);
-
-        return max(0, $end - $start);
-    }
-
     private function formatMinutes(int $minutes): string
     {
         if (0 === $minutes) {