docs/superpowers/specs/2026-06-08-hours-day-export-design.md

@@ -0,0 +1,170 @@
+# 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`.