Story QR-013 :¶

Module de régularisation directe RH : qr-attendance Tranche : QR-T4-001 (partielle : création directe RH) Contexte de marque : [LES DEUX] Papillon HR Suite + ALTARYS ENTERPRISE HR Suite Priorité : 13 Dépend de : QR-012 (logique d'approbation + de recalcul existante) Peut être développé en parallèle avec : QR-015, QR-017 Ordre de fusion : Après QR-012 Complexité estimée : S PRD User Stories : US-QR-006

Objectif¶

Permettre au personnel RH de créer des régularisations directes qui contournent le workflow de demande de l'employé et d'approbation du responsable. Une régularisation directe est automatiquement approuvée lors de sa création (le service RH est à la fois créateur et approbateur), déclenche immédiatement le recalcul de DailyAttendance et notifie l'employé concerné. Cela prend en charge les scénarios opérationnels dans lesquels les RH corrigent les enregistrements de présence de manière proactive.

Portée du backend¶

Entités et enregistrements¶

Aucune nouvelle table. Étend RegularizationService à partir de QR-012.

Migrations Flyway¶

Aucune.

Couche de référentiels¶

Aucun nouveau référentiel. Utilise le RegularizationRequestRepository existant.

Couche de service¶

RegularizationService.directCreate(request, hrId) : - Crée une RegularizationRequest avec : - status = APPROVED - isDirectCreate = true - requestedBy = hrId - approvedBy = hrId - approvedAt = now() - Déclenche le recalcul de DailyAttendance (réutilise la logique de QR-012) - Envoie une notification à l'employé : « Votre pointage a été corrigé par les RH. »

Method	Path	Request Body	Response	Auth
POST	`/api/v1/qrcontr/regularizations/direct`	`CreateRegularizationRequest`	`ApiResponse<RegularizationResponse>`	HR (P2)
### DTO

Réutilise les objets CreateRegularizationRequest et RegularizationResponse de QR-011.

Règles de validation¶

Même validation que pour QR-011 : - reason est obligatoire - Au moins un champ temporel doit être fourni (correctedClockIn ou correctedClockOut) - date doit faire référence à un enregistrement DailyAttendance existant - employeeId doit correspondre à un employé valide au sein du même tenant

Considérations multi-tenant¶

Toutes les requêtes de régularisation filtrent par tenant_id. Les RH ne peuvent créer des régularisations directes que pour les employés de leur propre locataire.

Portée du frontend¶

Pages et routes¶

Aucune nouvelle route. Le formulaire est déclenché à partir des vues existantes du tableau de bord.

Composants¶

DirectRegularizationForm : - Déclenché depuis le tableau de bord en balayant vers la gauche sur la ligne de l'employé (RH uniquement), ou depuis la fiche journalière de l'employé - Réutilise le composant RegularizationForm de QR-011 mais avec l'en-tête « Régularisation directe » et sans étape PENDING - Message de confirmation : « Régularisation enregistrée. L'employé sera informé de la correction. »

États de l'interface utilisateur¶

State	Behavior	French Copy
Loading	N/A (form is local)	—
Empty	Pre-filled with employee + date from context	—
Error	Inline validation	Same as QR-011
Offline	Form works, submit queued	"Regularisation sauvegardee — sera envoyee des la reconnexion."
Success	Animated checkmark	"Regularisation enregistree. L'employe sera notifie de la correction."

Comportement adaptatif¶

360px : formulaire en bas de page (une seule étape — aucun assistant n'est nécessaire puisque le service RH sait quoi remplir)
768px : en bas de page
1024px+ : panneau latéral

Interactions¶

Balayage vers la gauche sur la ligne de l'employé dans le tableau de bord → ouvre DirectRegularizationForm
Employé + date préremplis à partir du contexte
Soumettre → coche animée → le formulaire se ferme
Hors ligne : le formulaire est soumis à la file d'attente locale, synchronisation lors de la connexion

Critères d'acceptation¶

```gherkin AC-001: HR direct-create auto-approved regularization Given I am HR When I create a direct regularization Then it is auto-approved (no pending step) and recorded with HR as both creator and approver

AC-002: Employee notification on HR correction Given I create a direct regularization When it is saved Then the employee is notified that their record was corrected ```---

OHADA et règles réglementaires¶

FR-QR-064 : La régularisation directe est consignée dans la piste d'audit avec les RH comme acteur
Les événements horodatés d'origine sont conservés — la régularisation est un enregistrement additif, et non une modification destructive

Normes et conventions¶

docs/standards/java-spring-guidelines.md
docs/standards/api-guidelines.md
docs/standards/react-typescript-guidelines.md
docs/standards/offline-sync-guidelines.md

Exigences de test¶

Tests unitaires¶

RegularizationService.directCreate : définit status=APPROVED, isDirectCreate=true, requestedBy=hrId, approvedBy=hrId
RegularizationService.directCreate : déclenche le recalcul de DailyAttendance
Validation : motif obligatoire, au moins un champ de temps obligatoire

Tests d'intégration¶

POST /regularizations/direct → 201 avec statut APPROVED
POST /regularizations/direct avec un rôle non-RH → 403
POST /regularizations/direct → DailyAttendance recalculé correctement
Isolation des locataires : le service RH du locataire A ne peut pas régulariser un employé du locataire B

Ce que l'assurance qualité va valider¶

Le service RH crée une régularisation directe à partir d'une action de balayage sur le tableau de bord
Vérifier que la régularisation est automatiquement approuvée (aucune étape en attente)
Vérifier que l'employé reçoit une notification
Vérifier que la présence quotidienne est recalculée
Hors ligne : le formulaire fonctionne et se synchronise lors de la reconnexion

Hors du périmètre¶

Workflow de demande employé/responsable (QR-011)
Workflow d'approbation (QR-012)
Régularisation en masse (V2)

Définition de « Terminé »¶

[ ] Endpoint POST /regularizations/direct implémenté
[ ] DailyAttendance recalculé lors de la création directe
[ ] Le formulaire frontend fonctionne à partir de l'action de balayage du tableau de bord
[ ] Les 5 états de l'interface utilisateur implémentés (chargement, vide, erreur, hors ligne, succès)
[ ] Le micro-texte en français correspond 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
[ ] Écriture et synchronisation hors ligne fonctionnelles
[ ] Entrées de piste d'audit pour la régularisation directe
[ ] Pas de any en TypeScript, pas de types bruts en Java
[ ] Réponses API conformes au format d'enveloppe standard
[ ] ./gradlew test est vert
[ ] ./gradlew spotlessApply réussit