SIRH/docs/superpowers/specs/2026-06-11-night-hours-contingent-export-design.md

# Export « Contingent H.nuit »

Date : 2026-06-11
Statut : validé (design)

## Objectif

Ajouter un nouvel export PDF sur la **liste des employés** : un tableau du
contingent d'heures de nuit, employés en lignes, mois en colonnes. Chaque mois
porte deux sous-colonnes : **Total H.nuit** (heures travaillées de nuit) et
**Total N.jours** (nombre de nuits où ≥ 4h ont été travaillées de nuit).

## Décisions cadrées

- **Période** : année civile Janvier → Décembre, choisie via un sélecteur d'année
  dans le drawer (réutilise `exportYearOptions`).
- **Fenêtre de nuit** : 21h → 6h — on **réutilise le calcul existant** de l'app
  (constante `[0,360]` + `[1260,1440]` minutes, projection J+1 pour les shifts
  traversant minuit). NB : la demande initiale mentionnait 21h-5h ; arbitré sur
  21h→6h pour rester cohérent avec le reste de l'application.
- **Règle « 1 jour »** : un jour compte 1 dans « N.jours » dès que les minutes de
  nuit du jour ≥ 240 (4h).
- **Conducteurs** : inclus. Leurs minutes de nuit = champ manuel
  `WorkHour.nightHoursMinutes` (pas de fenêtre horaire — total saisi). La règle
  ≥ 240 min = 1 jour s'applique aussi.
- **Non-conducteurs** : minutes de nuit calculées depuis les plages
  matin/après-midi/soir via la fenêtre 21h→6h.
- **Pas de crédit** absence/férié : on ne compte que les heures de nuit
  réellement travaillées (pas de crédit virtuel férié ni crédit absence).
- **Pas de colonne « Total annuel »** (hors périmètre pour l'instant).
- **Mise en page** : A4 **paysage**.
- **Groupement / tri** : par site, identique au day-export et au calendrier —
  sites triés par `displayOrder` puis nom ; employés triés par `displayOrder`,
  puis nom, puis prénom.

## Architecture

### Frontend

`frontend/pages/employees/index.vue` (drawer Export existant) :
- Ajouter une option `{ label: 'Contingent H.nuit', value: 'night-contingent' }`
  dans `exportTypeOptions`.
- Quand `exportChoice === 'night-contingent'` : afficher le sélecteur d'année
  (réutiliser le `MalioSelect` année déjà utilisé par `yearly-hours`).
- `isExportValid` : valide si une année est choisie.
- `handleExportValidate` : `await printPdf('/night-hours-contingent/print?year=' + exportYear)`.

Aucun sélecteur de site (cohérent avec les autres exports de ce drawer — le
périmètre vient du back via `findScoped`).

### Backend

**Endpoint** : `GET /night-hours-contingent/print?year=YYYY`
- Operation API Platform custom (Provider, output PDF `Response`), `ROLE_USER`.
- `year` : entier validé 2000-2100, défaut = année courante.

**Provider** `App\State\NightHoursContingentPrintProvider`
1. Auth + parse `year`.
2. `employees = employeeRepository->findScoped($user)` (périmètre admin / chef de site).
3. Garder les employés ayant ≥ 1 période de contrat intersectant
   `[YYYY-01-01 ; YYYY-12-31]` (helper `hasContractInRange`, même esprit que
   `AbsencePrintProvider`/`SalaryRecapPrintProvider`).
4. Grouper par site ; trier sites par `displayOrder` puis nom ; trier employés
   intra-site par `displayOrder`, nom, prénom.
5. Construire les lignes via `NightContingentExportBuilder`.
6. Rendre `templates/night-hours-contingent/print.html.twig` → Dompdf (paysage).

**Builder** `App\Service\WorkHours\NightContingentExportBuilder`
- `buildRows(list<Employee> $employees, int $year): list<NightContingentRow>`
- Pour chaque employé : charge ses `WorkHour` de l'année (1 requête par lot ou
  par employé selon le repo existant), répartit par mois (1..12).
- Par jour : `nightMinutes = NightHoursCalculator::nightMinutesForWorkHour($wh, $isDriverThatDay)`.
  - Driver ce jour-là → `nightHoursMinutes ?? 0`.
  - Non-driver → somme des `nightIntervalMinutes` sur les 3 plages.
- Agrégats par mois : `nightMinutesTotal += nightMinutes` ;
  `if (nightMinutes >= 240) nightDays += 1`.
- Retour DTO : `{ employeeId, employeeName, isDriver, months: [{nightMinutes, nightDays} × 12] }`.

> Le statut driver est résolu **par date** (un employé peut changer de nature de
> contrat dans l'année), via le mécanisme existant (`EmployeeContractResolver` /
> période de contrat couvrant la date du `WorkHour`). On suit l'approche déjà en
> place dans les providers heures pour résoudre `isDriver` à la date.

**Service partagé** `App\Service\WorkHours\NightHoursCalculator`
- Extrait la logique 21h→6h aujourd'hui **dupliquée** dans
  `WorkHourWeeklySummaryProvider::nightIntervalMinutes/computeMetrics` et
  `YearlyHoursExportBuilder::nightIntervalMinutes/computeMetrics`.
- Méthodes :
  - `nightIntervalMinutes(?string $from, ?string $to): int` (fenêtres
    `[0,360]` + `[1260,1440]`, projection J+1).
  - `nightMinutesFromRanges(WorkHour $wh): int` (somme sur les 3 plages).
  - `nightMinutesForWorkHour(WorkHour $wh, bool $isDriver): int`
    (driver → `nightHoursMinutes ?? 0`, sinon `nightMinutesFromRanges`).
- `WorkHourWeeklySummaryProvider` et `YearlyHoursExportBuilder` délèguent à ce
  service pour la partie nuit (résultats identiques garantis ; les tests
  existants couvrent la non-régression).

### Template

`templates/night-hours-contingent/print.html.twig`
- A4 paysage.
- En-tête : « Contingent heures de nuit — {{ year }} », date d'export.
- Colonnes : `Nom` + 12 groupes de mois, chacun deux sous-colonnes
  `H.nuit` / `N.jours`.
- Lignes d'en-tête de site colorées (couleur site), comme le day-export.
- `H.nuit` formaté `12h30` (helper minutes → HH h MM), `N.jours` entier.
- Mois sans données → `0h00` / `0` (ou vide selon rendu — défaut 0).

## Tests

- `NightHoursCalculatorTest` : fenêtre 21h→6h, shift traversant minuit
  (21:00→05:00 = 8h nuit), plage de jour pur (0 nuit), plages nulles.
- `NightContingentExportBuilderTest` : agrégation mensuelle, règle ≥4h=1 jour
  (3h59 → 0 jour, 4h → 1 jour), conducteur via `nightHoursMinutes`, employé
  multi-mois.
- Non-régression : `make test` (les tests existants de
  `WorkHourWeeklySummaryProvider` / `YearlyHoursExportBuilder` valident le
  refactor du service partagé).

## Documentation à mettre à jour (même intervention)

- `doc/functional-rules.md` : nouvelle section export contingent nuit.
- `CLAUDE.md` : entrée sous une rubrique export.
- `frontend/data/documentation-content.ts` : article utilisateur (niveau admin/
  chef de site).

## Hors périmètre

- Colonne total annuel.
- Sélecteur de site dans le drawer.
- Export depuis un autre écran que la liste employés.
- Changement de la fenêtre de nuit ailleurs dans l'app (reste 21h→6h partout).