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

235 lines
8 KiB
Markdown
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 :**
```json
{
"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
```env
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`
```typescript
{
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)
```typescript
{
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
Reference in a new issue View git blame Copy permalink