renaud/espace-paie-odentas
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
espace-paie-odentas/VIREMENTS_SALAIRES_STAFF_FEATURE.md

8 KiB
Raw Permalink Blame History

Amélioration de la page Staff - Virements Salaires

Résumé des modifications

Cette implémentation ajoute la fonctionnalité complète de création et génération de PDF pour les virements de salaires dans l'interface Staff.

Fichiers créés

1. /app/api/staff/virements-salaires/generate-pdf/route.ts

API route pour générer les PDFs de feuilles d'appel via PDFMonkey.

Fonctionnalités :

  • Authentification Staff requise
  • Récupère les détails du virement de salaire (salary_transfer)
  • Récupère les contrats de la période (filtrés par mois de payment_date)
  • Construit le payload PDFMonkey selon le format du workflow n8n
  • Génère le PDF via l'API PDFMonkey (template F4BCB5FF-1AB1-4CEE-B57F-82A6B9893E9E)
  • Polling du statut de génération (15 tentatives max, intervalle 3s)
  • Téléchargement du PDF généré
  • Upload sur S3 dans virements-salaires/{org_id}/{transfer_id}-{timestamp}.pdf
  • Mise à jour de salary_transfers.callsheet_url avec l'URL S3

Payload PDFMonkey :

{
  "document": {
    "document_template_id": "F4BCB5FF-1AB1-4CEE-B57F-82A6B9893E9E",
    "status": "pending",
    "payload": {
      "organisation": "Nom de l'organisation",
      "periode": "Janvier 2025",
      "date_echeance": "15/01/2025",
      "total_net": "1234,56",
      "contrats": [
        {
          "nom": "Dupont",
          "prenom": "Jean",
          "iban": "FR76...",
          "montant_net": "456,78",
          "date_paiement": "20/01/2025"
        }
      ]
    }
  }
}

2. /app/api/staff/virements-salaires/create/route.ts

API route pour créer un nouvel enregistrement de virement de salaire.

Fonctionnalités :

  • Authentification Staff requise
  • Validation des champs obligatoires : org_id, period_month, deadline, mode
  • Vérification que l'organisation existe
  • Insertion dans la table salary_transfers
  • Retourne le nouvel enregistrement créé

Champs du formulaire :

  • org_id (requis) : ID de l'organisation
  • period_month (requis) : Mois de la période (format YYYY-MM)
  • period_label (optionnel) : Libellé de la période (ex: "Janvier 2025")
  • deadline (requis) : Date d'échéance (format YYYY-MM-DD)
  • mode (requis) : Mode de virement (SEPA, VIREMENT, odentas_reverse)
  • total_net (optionnel) : Total net (calculé automatiquement lors de la génération PDF)
  • notes (optionnel) : Notes internes

Fichiers modifiés

3. /components/staff/SalaryTransfersGrid.tsx

Composant client amélioré avec création et génération de PDF.

Nouvelles fonctionnalités :

A. Bouton de création

  • Bouton "Créer un virement" en haut de la page
  • Ouvre un modal avec formulaire complet

B. Modal de création

  • Formulaire avec tous les champs nécessaires
  • Validation côté client (champs requis)
  • Auto-génération du period_label basé sur period_month
  • Sélection d'organisation via dropdown
  • Sélection du mode (SEPA/VIREMENT/odentas_reverse)
  • Appel à l'API /api/staff/virements-salaires/create
  • Mise à jour temps réel de la liste après création

C. Colonne Actions

  • Nouvelle colonne "Actions" dans le tableau
  • Bouton "Générer PDF" pour chaque ligne
    • État "Génération..." pendant le traitement
    • État "Regénérer PDF" si déjà généré
    • Confirmation avant génération
  • Appel à l'API /api/staff/virements-salaires/generate-pdf
  • Mise à jour de l'URL de la feuille d'appel après génération

D. États et gestion

  • showCreateModal : contrôle l'affichage du modal
  • createForm : état du formulaire de création
  • creating : indicateur de création en cours
  • generatingPdfForId : ID du transfert en cours de génération PDF
  • Fonctions handleCreateTransfer() et handleGeneratePdf()

Architecture technique

Flux de création

  1. Utilisateur Staff clique sur "Créer un virement"
  2. Modal s'ouvre avec formulaire
  3. Utilisateur remplit les champs obligatoires
  4. Soumission du formulaire → POST /api/staff/virements-salaires/create
  5. API valide et insère dans salary_transfers
  6. Mise à jour temps réel via Supabase Realtime
  7. Modal se ferme, nouvel enregistrement visible dans le tableau

Flux de génération PDF

  1. Utilisateur Staff clique sur "Générer PDF" pour un virement
  2. Confirmation demandée
  3. POST /api/staff/virements-salaires/generate-pdf avec salary_transfer_id
  4. API récupère les contrats de la période
  5. Construction du payload PDFMonkey
  6. Appel à l'API PDFMonkey pour créer le document
  7. Polling du statut (max 15 tentatives, 3s entre chaque)
  8. Téléchargement du PDF généré
  9. Upload sur S3
  10. Mise à jour de salary_transfers.callsheet_url
  11. Mise à jour de l'interface (URL du PDF visible, bouton devient "Regénérer PDF")

Sécurité

  • Toutes les routes API vérifient l'authentification Supabase
  • Vérification du statut Staff via users.is_staff
  • Utilisation du Service Role Key pour les opérations côté serveur
  • Bearer token requis dans les headers

Variables d'environnement requises

NEXT_PUBLIC_SUPABASE_URL=...
SUPABASE_SERVICE_ROLE_KEY=...
PDFMONKEY_URL=https://api.pdfmonkey.io/api/v1/documents
PDFMONKEY_API_KEY=...
AWS_REGION=eu-west-3
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_S3_BUCKET=nouvel-espace-paie

Filtrage des contrats

Les contrats sont filtrés selon la logique suivante :

  • Contrats de l'organisation (org_id du virement)
  • Contrats ayant une payment_date non nulle
  • Le mois de payment_date doit correspondre au mois de period_month

Exemple :

  • period_month = "2025-01" (Janvier 2025)
  • Contrats inclus : ceux avec payment_date entre "2025-01-01" et "2025-01-31"

Format des données

Structure salary_transfers

{
  id: string;
  org_id: string;
  period_month: string; // Format YYYY-MM-DD
  period_label: string | null;
  mode: string; // SEPA, VIREMENT, odentas_reverse
  deadline: string; // Format YYYY-MM-DD
  total_net: string | number | null;
  callsheet_url: string | null; // URL S3 du PDF
  notification_sent: boolean | null;
  notification_ok: boolean | null;
  client_wire_received_at: string | null;
  notes: string | null;
  created_at: string;
  updated_at: string;
}

Structure cddu_contracts (champs utilisés)

{
  id: string;
  org_id: string;
  employee_first_name: string;
  employee_last_name: string;
  employee_iban: string;
  payment_date: string; // Format YYYY-MM-DD
  net_amount: string | number;
}

Tests recommandés

  1. Création d'un virement

    • Vérifier que tous les champs obligatoires sont validés
    • Vérifier que le nouvel enregistrement apparaît dans la liste
    • Vérifier que l'auto-génération du period_label fonctionne

  2. Génération de PDF

    • Créer un virement pour une période avec des contrats
    • Cliquer sur "Générer PDF"
    • Vérifier que le PDF est créé sur S3
    • Vérifier que l'URL est mise à jour dans callsheet_url
    • Vérifier le contenu du PDF (organisation, période, contrats)

  3. Cas limites

    • Virement pour une période sans contrats (doit générer un PDF vide ou avec 0 contrats)
    • Regénération d'un PDF existant
    • Erreurs réseau (timeout PDFMonkey, erreur S3)

Améliorations futures possibles

  1. Calcul automatique du total_net

    • Lors de la création, proposer un calcul automatique basé sur les contrats de la période

  2. Aperçu des contrats

    • Afficher le nombre de contrats qui seront inclus dans le PDF avant génération

  3. Notifications

    • Intégrer l'envoi de notifications après génération du PDF

  4. Historique

    • Garder l'historique des générations (versions multiples du PDF)

  5. Validation des IBANs

    • Vérifier que tous les contrats de la période ont des IBANs valides avant génération

  6. Export Excel

    • Proposer un export Excel en plus du PDF

Notes de compatibilité

  • Compatible avec Next.js 14+ (App Router)
  • Utilise Supabase Realtime pour les mises à jour en temps réel
  • Compatible avec le workflow n8n existant (même format de payload)
  • Template PDFMonkey : F4BCB5FF-1AB1-4CEE-B57F-82A6B9893E9E