espace-paie-odentas/BULK_SEPA_UPDATE_FEATURE.md

Fonctionnalité de Modification en Masse des Dates de Factures

Résumé

Cette fonctionnalité permet aux utilisateurs staff de modifier en masse différents types de dates sur plusieurs factures en même temps depuis la page /staff/facturation :

• Date de prélèvement SEPA (sepa_day)
• Date de facture (invoice_date)
• Date d'échéance (due_date)

Fonctionnalités implémentées

Interface utilisateur

1. Checkboxes de sélection :

   • Une checkbox "Tout sélectionner" dans l'en-tête du tableau
   • Une checkbox par ligne de facture pour la sélection individuelle

2. Bandeau d'actions :

   • Apparaît automatiquement quand au moins une facture est sélectionnée
   • Affiche le nombre de factures sélectionnées
   • Contient trois boutons d'action :
     • "Modifier date facture" (vert) - Met à jour invoice_date
     • "Modifier date échéance" (orange) - Met à jour due_date
     • "Modifier date SEPA" (bleu) - Met à jour sepa_day
   • Bouton "Annuler" pour effacer la sélection

3. Modals de saisie :

   • Interface dédiée pour chaque type de date
   • Validation côté client appropriée selon le type de date
   • Gestion des états de chargement
   • Messages de confirmation et d'erreur

Backend

4. APIs de mise à jour en masse :
   • /api/staff/facturation/bulk-update-sepa - Pour les dates SEPA
   • /api/staff/facturation/bulk-update-invoice-date - Pour les dates de facture
   • /api/staff/facturation/bulk-update-due-date - Pour les dates d'échéance
   • Endpoints POST protégés (accès staff uniquement)
   • Validation des données d'entrée
   • Validation de sécurité (limite de 100 factures par batch)
   • Mise à jour atomique dans Supabase
   • Gestion d'erreurs complète

Architecture technique

Frontend

• Fichier modifié : app/(app)/staff/facturation/page.tsx
• Nouvelles dépendances : Icône Calendar de Lucide React
• État React :
  • selectedInvoices: Set<string> pour les factures sélectionnées
  • showSepaModal: boolean pour l'affichage du modal SEPA
  • showInvoiceDateModal: boolean pour l'affichage du modal de date de facture
  • showDueDateModal: boolean pour l'affichage du modal de date d'échéance
  • newSepaDate: string pour la nouvelle date SEPA
  • newInvoiceDate: string pour la nouvelle date de facture
  • newDueDate: string pour la nouvelle date d'échéance

Backend

• Nouveaux fichiers :
  • app/api/staff/facturation/bulk-update-sepa/route.ts
  • app/api/staff/facturation/bulk-update-invoice-date/route.ts
  • app/api/staff/facturation/bulk-update-due-date/route.ts
• Méthode : POST pour tous les endpoints
• Protection : Vérification du statut staff
• Base de données : Table invoices

Utilisation

1. Aller sur /staff/facturation
2. Cocher les factures concernées (individuellement ou toutes)
3. Choisir l'action souhaitée dans le bandeau qui apparaît :
   • Modifier date facture : Change la date d'émission de la facture
   • Modifier date échéance : Change la date limite de paiement
   • Modifier date SEPA : Change la date de prélèvement automatique
4. Sélectionner la nouvelle date dans le modal correspondant
5. Confirmer l'action

Spécificités par type de date

Date de facture (invoice_date)

• Couleur : Vert
• Champ DB : invoice_date
• Validation : Format de date valide
• Restrictions : Aucune restriction de date passée

Date d'échéance (due_date)

• Couleur : Orange
• Champ DB : due_date
• Validation : Format de date valide
• Restrictions : Aucune restriction de date passée

Date SEPA (sepa_day)

• Couleur : Bleu
• Champ DB : sepa_day
• Validation : Format de date valide + date future obligatoire
• Restrictions : Date ne peut pas être dans le passé

Sécurité et validations

• ✅ Accès restreint aux utilisateurs staff uniquement
• ✅ Validation de format de date (YYYY-MM-DD) pour tous les types
• ✅ Validation que la date SEPA n'est pas dans le passé
• ✅ Limite de 100 factures par mise à jour
• ✅ Vérification de l'existence des factures avant mise à jour
• ✅ Mise à jour atomique avec rollback en cas d'erreur
• ✅ Journalisation des opérations

Messages d'erreur gérés

Erreurs communes à tous les endpoints

• invalid_invoice_ids : IDs de factures invalides
• invalid_date_format : Format de date incorrect
• too_many_invoices : Trop de factures (>100)
• some_invoices_not_found : Certaines factures n'existent pas
• unauthorized : Utilisateur non connecté
• forbidden : Accès non autorisé (non-staff)

Erreurs spécifiques par type

• invalid_sepa_date : Date SEPA invalide
• date_in_past : Date SEPA dans le passé (uniquement pour SEPA)
• invalid_invoice_date : Date de facture invalide
• invalid_due_date : Date d'échéance invalide

Tests recommandés

1. Test de sélection :

   • Sélection individuelle de factures
   • Sélection/désélection globale
   • Annulation de sélection

2. Test de validation par type de date :

   • Date SEPA : Date dans le passé (doit échouer), Date future (doit réussir)
   • Date facture : Date passée/future (doivent réussir)
   • Date échéance : Date passée/future (doivent réussir)
   • Format de date invalide pour tous les types

3. Test de sécurité :

   • Accès non-staff (doit échouer)
   • Trop de factures sélectionnées (doit échouer)

4. Test de mise à jour :

   • Mise à jour réussie pour chaque type de date
   • Rafraîchissement automatique des données
   • Messages de succès/erreur appropriés

5. Test d'UI :

   • Affichage/masquage correct des modals
   • Couleurs distinctives des boutons
   • States de chargement
   • Nettoyage des formulaires après annulation

Interface utilisateur

Bandeau d'actions

[X factures sélectionnées]  [Modifier date facture] [Modifier date échéance] [Modifier date SEPA] [Annuler]
                              ↑ Vert                 ↑ Orange                ↑ Bleu              ↑ Gris

Couleurs des boutons

• 🟢 Vert (bg-green-600) : Date de facture
• 🟠 Orange (bg-orange-600) : Date d'échéance
• 🔵 Bleu (bg-blue-600) : Date SEPA
• ⚫ Gris (bg-gray-500) : Annuler

Notes techniques

• La fonctionnalité utilise React Query pour la gestion des mutations et le cache
• Les modals utilisent un overlay avec position: fixed et z-index élevé
• Les styles suivent la convention Tailwind CSS existante du projet
• L'API suit les patterns de sécurité existants du projet
• Chaque type de date a son propre endpoint pour une meilleure modularité
• La validation côté client empêche les soumissions invalides
• La validation côté serveur assure la sécurité des données