Cas pratique QR-017 : Rapport mensuel de présence +¶

module d'exportation : qr-attendance Tranche : QR-T5-002 + QR-T5-004 Contexte de marque : [LES DEUX] Papillon HR Suite + ALTARYS ENTERPRISE HR Suite Priorité : 17 Dépend de : QR-012 (informations de régularisation dans les rapports) Peut être développé en parallèle avec : QR-018 Ordre de fusion : Avant QR-018 (service d'exportation partagé) Complexité estimée : M PRD User Stories : US-QR-011

Objectif¶

Créer le rapport mensuel de présence pour les employés individuels et les résumés au niveau des services, avec des capacités d'exportation vers Excel (.xlsx) et CSV. Le rapport mensuel des employés présente les détails quotidiens (heures prévues vs heures effectives, statut, heures supplémentaires, anomalies, régularisations) ainsi qu'une ligne de synthèse. Le résumé du service regroupe les statistiques de tous les employés. Les fichiers d'exportation utilisent les conventions de formatage françaises (dates au format JJ/MM/AAAA, heures au format HH:MM, virgule comme séparateur décimal, UTF-8 avec BOM pour le CSV).

Portée du backend¶

Entités et enregistrements¶

Aucune nouvelle table. Utilise les tables existantes DailyAttendance, Clock, RegularizationRequest.

Migrations Flyway¶

Aucune.

Couche de référentiel¶

Aucun nouveau repository. Étend les requêtes existantes sur DailyAttendance.

Couche de service¶

MonthlyAttendanceReportService : - generateEmployeeReport(tenantId, employeeId, month) : - Renvoie MonthlyEmployeeReport - Par ligne (une par jour ouvré) : date, jourDeLaSemaine, débutPrévu, finPrévue, heureD'arrivéeRéelle, heureDeDépartRéelle, minutesTravaillées, statut, minutesDeHeuresSupplémentaires, minutesDeDépartAnticipé, anomalies, régularisationsAppliquées - Résumé : totalWorkedHours, totalScheduledHours, totalOvertime (par tranche), totalLateCount+minutes, totalEarlyDepartureCount+minutes, totalAbsences, totalTeletravailDays, totalHolidays

DepartmentSummaryReportService : - generateDepartmentSummary(tenantId, departmentId, month) : - Renvoie DepartmentSummaryReport - Par ligne (une par employé) : nom, totalWorkedHours, totalOvertime, totalLateCount, totalEarlyDepartureCount, totalAbsences, totalTeletravail, attendanceRate (%)

ExcelExportService : - Utilise Apache POI pour générer des fichiers .xlsx - Format de date français : JJ/MM/AAAA, heure : HH:MM, séparateur décimal : virgule - En-tête de l'entreprise + titre du rapport dans les premières lignes - En-têtes stylisées, colonnes à taille automatique - Entreprise : inclut une ligne de signature en bas

CsvExportService: - UTF-8 avec BOM (pour la compatibilité Excel avec les caractères français) - Mêmes conventions de format que Excel (JJ/MM/AAAA, HH:MM, virgule comme séparateur décimal) - Séparateur point-virgule (norme CSV française)

Endpoints de l'API¶

Method	Path	Request Body	Response	Auth
GET	`/api/v1/qrcontr/reports/monthly-attendance`	`?employeeId=&month=2026-03`	`ApiResponse<MonthlyEmployeeReport>`	HR, Comptable
GET	`/api/v1/qrcontr/reports/department-summary`	`?departmentId=&month=2026-03`	`ApiResponse<DepartmentSummaryReport>`	HR, Manager (own dept)
GET	`/api/v1/qrcontr/reports/export`	`?type=monthly-attendance&employeeId=&month=&format=xlsx\\|csv`	File download (Content-Disposition)	HR, Comptable
### DTO

« MonthlyEmployeeReport » : - « employeeId » (UUID), « employeeName » (chaîne de caractères), « month » (année-mois) - summary (ReportSummary) : totalWorkedHours, totalScheduledHours, totalOvertimeByBand (Map), totalLateCount, totalLateMinutes, totalEarlyDepartureCount, totalEarlyDepartureMinutes, totalAbsences, totalTeletravailDays, totalHolidays - days (List) : date, jourDeLaSemaine, heureDeDébutPrévue, heureDeFinPrévue, heureD'arrivéeRéelle, heureDeDépartRéelle, minutesTravaillées, statut, minutesD'heuresSupplémentaires, minutesDeDépartAnticipé, anomalies, régularisationsAppliquées

DepartmentSummaryReport : - departmentId (UUID), departmentName (Chaîne), month (AnnéeMois) - employees (List) : employeeId, name, totalWorkedHours, totalOvertime, totalLateCount, totalEarlyDepartureCount, totalAbsences, totalTeletravail, attendanceRate

Règles de validation¶

Format month : AAAA-MM (obligatoire)
employeeId obligatoire pour le rapport de présence mensuel
departmentId requis pour le rapport récapitulatif par service
format doit être xlsx ou csv pour l'endpoint d'exportation
Le responsable ne peut accéder qu'au récapitulatif de son propre service

Considérations multi-tenant¶

Toutes les requêtes de rapport sont filtrées par tenant_id. Le responsable est limité à son propre service. Les RH et le comptable voient tout ce qui se trouve au sein de la location.

Portée du frontend¶

Pages et routes¶

/qrcontr/reports — Centre des rapports
/qrcontr/reports/monthly — Affichage du rapport de présence mensuel
/qrcontr/reports/department — Affichage du résumé par service

Composants¶

ReportHubPage (maquette de conception 3.13) : - Liens vers le rapport de présence mensuel et le rapport d'heures supplémentaires (QR-018)

MonthlyReportPage : - Sélecteur d'employés, sélecteur de mois, fiches récapitulatives, tableau quotidien

DepartmentSummaryPage : - Sélecteur de service, sélecteur de mois, tableau récapitulatif des employés

ExportButtons : - Boutons d'action flottants « Exporter vers Excel » + « Exporter vers CSV » - Déclenche le téléchargement dans le navigateur au clic

ReportTable : - Tableau défilable avec en-têtes fixes - Première colonne fixe (date ou nom de l'employé) lors du défilement horizontal

États de l'interface utilisateur¶

State	Behavior	French Copy
Loading	Skeleton summary + table	—
Empty	No data for period	"Aucune donnee pour la periode selectionnee."
Error	Inline retry	"Impossible de generer le rapport. Reessayez."
Offline	Cached summaries only, full report requires server	"Rapport complet disponible en ligne uniquement."
Success	Summary cards + detailed table	—

Comportement adaptatif¶

360px : tableau à défilement horizontal (3 colonnes visibles), boutons d'exportation en bas
768px : 5 colonnes visibles, boutons d'exportation en bas
1024px+ : tableau complet avec toutes les colonnes, boutons d'exportation dans la barre d'outils

Interactions¶

Sélecteurs d'employé/service/mois : composants de menu déroulant/sélecteur
Tableau : défilement horizontal sur mobile, première colonne fixe
Exportation : déclenche le téléchargement dans le navigateur. Indicateur de chargement sur le bouton pendant la génération.
Entreprise : le fichier Excel inclut l'en-tête de l'entreprise et la ligne de signature

Critères d'acceptation¶

```gherkin AC-001: Monthly employee attendance sheet Given I select an employee and a month When I generate the report Then I see for each day: scheduled hours, actual clock-in, actual clock-out, worked hours, status, overtime hours, early departures, anomalies, regularizations applied And a summary row with: total worked hours, total overtime (by band), total late arrivals (count + minutes), total early departures, total absences, total teletravail days

AC-002: Department summary report Given I select a department and a month When I generate a department summary Then I see aggregated stats across all employees in that department

AC-003: Report export to Excel and CSV Given I generate any report When I click export Then I can download it as Excel (.xlsx) or CSV (.csv) with French date/time/decimal formatting ```---

OHADA et règles réglementaires¶

FR-QR-113 : encodage CSV UTF-8 avec BOM, dates au format JJ/MM/AAAA, heures au format HH:MM, décimales séparées par une virgule
Les rapports respectent l'obligation de conservation pendant 10 ans (TV-QR-003)
Les rapports alimentent le rapprochement de la paie (accès comptable)
Les registres de présence constituent une preuve légale en cas de litige du travail

Normes et conventions¶

docs/standards/java-Spring-guidelines.md
docs/standards/api-guidelines.md
docs/standards/react-typescript-guidelines.md

Exigences de test¶

Tests unitaires¶

MonthlyAttendanceReportService : calcul du rapport mensuel (totaux récapitulatifs, enregistrements journaliers)
DepartmentSummaryReportService : agrégation par service (statistiques par employé, taux de présence)
ExcelExportService : format de date français (JJ/MM/AAAA), format d'heure (HH:MM), séparateur décimal par virgule
CsvExportService : présence d'un BOM UTF-8, délimiteur point-virgule, formatage français

Tests d'intégration¶

GET /reports/monthly-attendance?employeeId=&month= → données du rapport correctes
GET /reports/department-summary?departmentId=&month= → résumé correct
GET /reports/export?type=monthly-attendance&format=xlsx → téléchargement du fichier avec le type de contenu correct
GET /reports/export?type=monthly-attendance&format=csv → téléchargement du fichier avec BOM
Non-RH/Comptable → 403
Manager accédant à un autre service → 403
Isolation des locataires vérifiée

Ce que l'assurance qualité va valider¶

Générer le rapport mensuel, vérifier l'exactitude des données par rapport aux données de présence connues
Générer le résumé du service, vérifier l'agrégation
Télécharger le fichier Excel, l'ouvrir dans Excel, vérifier la mise en forme en français
Télécharger le fichier CSV, l'ouvrir dans Excel, vérifier que les caractères français s'affichent correctement (BOM)
Comportement réactif du tableau à tous les points de rupture
Hors ligne : affichage du résumé mis en cache, le rapport complet affiche un message « en ligne uniquement »

Hors périmètre¶

Rapport sur les heures supplémentaires (QR-018)
Exportation au format PDF (Enterprise V2)
Rapports cumulés depuis le début de l'année (V2)
Envoi par e-mail/planification de rapports (V2)

Définition de « Terminé »¶

[ ] Les endpoints de génération de rapports renvoient des données correctes
[ ] L'exportation vers Excel avec Apache POI fonctionne correctement
[ ] L'exportation CSV avec BOM UTF-8 fonctionne correctement
[ ] Mise en forme française appliquée (JJ/MM/AAAA, HH:MM, décimales séparées par une virgule)
[ ] La page centrale des rapports contient des liens vers tous les types de rapports
[ ] L'affichage des rapports s'adapte à tous les points de rupture (360px, 768px, 1024px)
[ ] Les 5 états de l'interface utilisateur sont implémentés (chargement, vide, erreur, hors ligne, succès)
[ ] Les micro-textes en français correspondent exactement aux spécifications de conception
[ ] Tous les critères d'acceptation sont satisfaits manuellement
[ ] Tests unitaires écrits et réussis
[ ] Tests d'intégration écrits et réussis
[ ] Isolation multi-tenant vérifiée
[ ] Pas de any en TypeScript, pas de types bruts en Java
[ ] Les réponses API respectent le format d'enveloppe standard
[ ] ./gradlew test est vert
[ ] ./gradlew spotlessApply réussit