# Export PDF des heures — vue Jour (par sites)

**Date** : 2026-06-08
**Branche** : feature/SIRH-35-export-des-heures-employe

## Objectif

Ajouter un bouton **Exporter** sur l'écran « Heures », réservé aux administrateurs,
qui produit un **PDF d'une journée** reprenant les colonnes de la vue Jour (sans la
colonne de validation), pour les employés des sites sélectionnés, **regroupés par site**.

## Décisions validées

| Sujet | Choix |
|-------|-------|
| Format | PDF (Twig → Dompdf) |
| Période | Un seul jour |
| Orientation | A4 **portrait**, mise en page compacte (objectif : tenir sur une page ; débordement multipage seulement si le nombre d'employés l'impose) |
| Regroupement | Une section par site |
| Accès | `ROLE_ADMIN` uniquement |

## Comportement frontend

### Bouton

- Dans `frontend/pages/hours.vue`, à droite du titre « Heures » (le conteneur titre est
  déjà `flex flex-wrap items-center justify-between`).
- Visible uniquement si `isAdmin` (déjà exposé par `useHoursPage`).
- Style cohérent avec les autres boutons d'action de l'app ; libellé « Exporter »
  (préfixe non requis ici, ce n'est pas un « + Ajouter »).

### Drawer `HoursDayExportDrawer.vue`

Nouveau composant utilisant `AppDrawer` (mode create — bouton centré).

Champs :
1. **Date** — champ date (input date), prérempli avec `selectedDate` de l'écran.
2. **Sites** — `MalioSelectCheckbox` avec `display-select-all`, mêmes options que la
   toolbar (`sites` du composable), présélectionné sur `selectedSiteIds` courants.

Bouton **« Exporter »** : désactivé si aucune date ou aucun site sélectionné.

### Déclenchement

- À la validation : `usePdfPrinter().printPdf(url)` avec
  `GET /work-hours/day-export?workDate=YYYY-MM-DD&siteIds=1,2,3`.
- Le téléchargement réutilise le pattern blob existant (`usePdfPrinter`).
- État `isLoading` sur le bouton pendant la génération.

### Câblage dans `hours.vue` / `useHoursPage.ts`

- `hours.vue` gère l'état d'ouverture du drawer et passe `sites`, `selectedSiteIds`,
  `selectedDate`, `isAdmin`.
- L'appel d'export peut vivre dans un petit handler local (`hours.vue`) ou dans le
  composable ; au choix de l'implémentation, en gardant `useHoursPage` comme source des
  données affichées.

## Portée des données (identique à l'écran Jour)

- Employés **non-conducteurs** (`isDriver !== true`).
- **Sous contrat** à la date choisie.
- Appartenant aux **sites cochés**.
- **Tous les employés sous contrat sont affichés**, même sans saisie (lignes vides) —
  cohérent avec la règle des exports heures annuelles.

## Colonnes du PDF

Mêmes colonnes que la vue Jour, **sans la colonne Valider** :

`Nom` · `Statut` · `Début matin` · `Fin matin` · `Début après-midi` ·
`Fin après-midi` · `Début soir` · `Fin soir` · `Jour` · `Nuit` · `Total`

- **Statut** : libellé d'absence (ou formation, ou nom du férié) si présent, sinon vide.
- **Heures** (`Début/Fin` matin/après-midi/soir) : valeurs `WorkHour` brutes (`HH:MM`),
  vides si non saisies.
- **Jour / Nuit / Total** : calculés comme à l'écran — minutes jour vs nuit, total
  incluant le crédit d'absence (`countAsWorkedHours`) et le **crédit virtuel férié**
  (`HolidayVirtualHoursResolver`).
- Week-ends / fériés : lignes grisées/colorées comme dans les templates existants.

## Architecture backend

### ApiResource `WorkHourDayExport`

`src/ApiResource/WorkHourDayExport.php` — calqué sur `EmployeeYearlyHoursBulkPrint` :

```php
new Get(
    uriTemplate: '/work-hours/day-export',
    provider: WorkHourDayExportProvider::class,
    parameters: [
        new QueryParameter(key: 'workDate', required: true),
        new QueryParameter(key: 'siteIds', required: true),
    ],
    security: "is_granted('ROLE_ADMIN')"
)
```

### Provider `WorkHourDayExportProvider`

`src/State/WorkHourDayExportProvider.php` :

1. Lire/valider `workDate` (`Y-m-d`) et `siteIds` (CSV d'entiers).
2. Charger les employés (`EmployeeRepository::findAll()` — feature admin-only),
   filtrer : non-drivers, site ∈ siteIds.
3. Pour chaque site (ordre `displayOrder`), trier les employés par nom.
4. Filtrer les employés sous contrat à la date (le builder ignore déjà les jours hors
   contrat — un employé sans contrat ce jour produit une ligne vide à exclure).
5. Construire les lignes via `YearlyHoursExportBuilder` (méthode dédiée, voir ci-dessous).
6. Rendre le Twig → Dompdf (`A4`, `portrait`), renvoyer `Response` binaire avec
   `Content-Disposition: attachment; filename="heures_jour_YYYY-MM-DD.pdf"`.

### Réutilisation `YearlyHoursExportBuilder`

Ajouter une méthode publique :

```php
/**
 * @param list<Employee> $employees
 * @return list<array{employeeId:int, employeeName:string, statut:?string,
 *   morningFrom:string, morningTo:string, afternoonFrom:string, afternoonTo:string,
 *   eveningFrom:string, eveningTo:string, dayHours:string, nightHours:string,
 *   total:string, isWeekend:bool, hasContract:bool}>
 */
public function buildDayRowsForEmployees(array $employees, DateTimeImmutable $date): array
```

- Réutilise les helpers privés existants (`computeMetrics`, résolution d'absences,
  `HolidayVirtualHoursResolver`, `EmployeeContractResolver`, fériés) — **source unique
  de vérité** pour le calcul des cellules d'une journée.
- Émet en plus `dayHours` / `nightHours` (issus de `WorkMetrics.dayMinutes` /
  `nightMinutes`) que l'export annuel n'affichait pas par ligne en mode TIME.
- Les employés sans contrat ce jour sont exclus (pas de ligne).
- Le `statut` agrège absence / formation / libellé férié (réutilise la logique de
  résolution d'absence/formation déjà présente dans le contexte jour si nécessaire).

> Note : la vue Jour mélange potentiellement modes TIME et PRESENCE selon le contrat à
> la date. Pour l'export, on suit le mode résolu à la date (comme l'écran). En mode
> PRESENCE, les cellules horaires restent vides et `Total` exprime les demi-journées,
> identique à l'affichage écran.

### Template `templates/work-hour-day-export/print.html.twig`

- A4 portrait, marges fines, police ~9px (réf. `employee-yearly-hours/print.html.twig`).
- Barre de titre : « Heures — {date} » + date d'export en haut à droite.
- Une `<h2>` par site, suivie d'un tableau avec les 11 colonnes ci-dessus.
- Week-ends / fériés grisés (`#c0c0c0` / `#b3e5fc`) comme les templates existants.
- `table-layout: auto`, largeurs compactes pour viser une page.

## Limites connues

- Un grand nombre d'employés (beaucoup de sites cochés) peut déborder sur plusieurs
  pages — on vise une page sans la garantir.
- Pas de risque mémoire particulier (un seul jour, volume très inférieur à l'export
  annuel tous employés).

## Documentation à mettre à jour (règles CLAUDE.md)

1. `doc/` : nouvelle section (ou ajout à un doc heures existant) décrivant l'export jour.
2. `frontend/data/documentation-content.ts` : entrée niveau **admin** dans la section
   Heures.
3. `CLAUDE.md` : note sous la section heures/exports (provider, builder réutilisé,
   colonnes, scope identique écran, portrait).

## Tests

- Test unitaire `YearlyHoursExportBuilder::buildDayRowsForEmployees` : un employé TIME
  avec saisie (vérifier day/night/total), un employé sans contrat (exclu), un jour férié
  (crédit virtuel), une absence `countAsWorkedHours`.
- (Optionnel) test provider : validation des paramètres `workDate` / `siteIds`.