231 lines
6.5 KiB
Markdown
231 lines
6.5 KiB
Markdown
# 📋 Virements Salaires Staff - Résumé rapide
|
||
|
||
## ✅ Ce qui a été implémenté
|
||
|
||
### 🎯 Fonctionnalités principales
|
||
|
||
1. **Création de virements de salaires**
|
||
- Formulaire modal avec tous les champs nécessaires
|
||
- Validation des données côté client et serveur
|
||
- Insertion dans la table `salary_transfers`
|
||
|
||
2. **Génération de PDF via PDFMonkey**
|
||
- Récupération automatique des contrats de la période
|
||
- Construction du payload selon le format n8n
|
||
- Génération via PDFMonkey (template F4BCB5FF-1AB1-4CEE-B57F-82A6B9893E9E)
|
||
- Upload automatique sur S3
|
||
- Mise à jour de l'URL dans la base de données
|
||
|
||
3. **Interface utilisateur**
|
||
- Bouton "Créer un virement" en haut de la page
|
||
- Modal de création avec formulaire complet
|
||
- Colonne "Actions" dans le tableau
|
||
- Bouton "Générer PDF" par ligne
|
||
- États visuels (en cours, succès)
|
||
|
||
## 📁 Fichiers créés
|
||
|
||
### APIs
|
||
- `app/api/staff/virements-salaires/create/route.ts` - Création d'un virement
|
||
- `app/api/staff/virements-salaires/generate-pdf/route.ts` - Génération du PDF
|
||
|
||
### Documentation
|
||
- `VIREMENTS_SALAIRES_STAFF_FEATURE.md` - Documentation complète de la fonctionnalité
|
||
- `VIREMENTS_SALAIRES_TEST_GUIDE.md` - Guide de test détaillé
|
||
- `VIREMENTS_SALAIRES_SQL_QUERIES.md` - Requêtes SQL utiles
|
||
- `VIREMENTS_SALAIRES_STAFF_README.md` - Ce fichier
|
||
|
||
## 📁 Fichiers modifiés
|
||
|
||
- `components/staff/SalaryTransfersGrid.tsx` - Ajout du modal et des actions
|
||
|
||
## 🚀 Démarrage rapide
|
||
|
||
### 1. Configuration requise
|
||
|
||
Vérifier que ces variables sont dans `.env.local` :
|
||
|
||
```env
|
||
# PDFMonkey
|
||
PDFMONKEY_URL=https://api.pdfmonkey.io/api/v1/documents
|
||
PDFMONKEY_API_KEY=<votre_clé>
|
||
|
||
# AWS S3
|
||
AWS_REGION=eu-west-3
|
||
AWS_ACCESS_KEY_ID=<votre_clé>
|
||
AWS_SECRET_ACCESS_KEY=<votre_clé>
|
||
AWS_S3_BUCKET=nouvel-espace-paie
|
||
```
|
||
|
||
### 2. Accès à la page
|
||
|
||
- URL : `/staff/virements-salaires`
|
||
- Nécessite : compte Staff (`is_staff = true`)
|
||
|
||
### 3. Utilisation
|
||
|
||
**Créer un virement :**
|
||
1. Cliquer sur "+ Créer un virement"
|
||
2. Remplir le formulaire (organisation, période, échéance, mode)
|
||
3. Cliquer sur "Créer"
|
||
|
||
**Générer le PDF :**
|
||
1. Dans la colonne "Actions", cliquer sur "Générer PDF"
|
||
2. Confirmer
|
||
3. Attendre la génération (10-30 secondes)
|
||
4. Le PDF est automatiquement uploadé sur S3
|
||
|
||
## 🔧 Architecture technique
|
||
|
||
### Flux de création
|
||
```
|
||
UI (Modal) → POST /api/staff/virements-salaires/create
|
||
→ Validation → Insert DB → Realtime update → UI refresh
|
||
```
|
||
|
||
### Flux de génération PDF
|
||
```
|
||
UI (Bouton) → POST /api/staff/virements-salaires/generate-pdf
|
||
→ Récupération contrats → Payload PDFMonkey
|
||
→ Génération PDF → Polling statut → Download PDF
|
||
→ Upload S3 → Update DB → UI refresh
|
||
```
|
||
|
||
## 📊 Filtrage des contrats
|
||
|
||
Les contrats inclus dans le PDF sont ceux qui respectent :
|
||
- Même `org_id` que le virement
|
||
- `payment_date` non nulle
|
||
- **Mois** de `payment_date` = **Mois** de `period_month`
|
||
|
||
Exemple :
|
||
```
|
||
period_month = "2025-01"
|
||
→ Inclut les contrats avec payment_date entre 2025-01-01 et 2025-01-31
|
||
```
|
||
|
||
## 📋 Payload PDFMonkey
|
||
|
||
```json
|
||
{
|
||
"document": {
|
||
"document_template_id": "F4BCB5FF-1AB1-4CEE-B57F-82A6B9893E9E",
|
||
"status": "pending",
|
||
"payload": {
|
||
"organisation": "Nom 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"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🧪 Tests rapides
|
||
|
||
1. **Test création** : Créer un virement avec des données valides
|
||
2. **Test génération** : Générer le PDF pour ce virement
|
||
3. **Test contenu** : Ouvrir le PDF et vérifier les données
|
||
4. **Test S3** : Vérifier que le fichier existe sur S3
|
||
5. **Test regénération** : Cliquer sur "Regénérer PDF"
|
||
|
||
## 🔍 Vérifications
|
||
|
||
### Console navigateur
|
||
```javascript
|
||
// Vérifier les logs Supabase Realtime
|
||
// Vérifier qu'il n'y a pas d'erreurs JavaScript
|
||
```
|
||
|
||
### Logs serveur
|
||
```
|
||
[staff/virements-salaires] Organizations count: X
|
||
```
|
||
|
||
### Base de données
|
||
```sql
|
||
-- Vérifier le virement créé
|
||
SELECT * FROM salary_transfers ORDER BY created_at DESC LIMIT 1;
|
||
|
||
-- Vérifier les contrats de la période
|
||
SELECT COUNT(*) FROM cddu_contracts
|
||
WHERE org_id = 'ORG_ID'
|
||
AND DATE_TRUNC('month', payment_date) = '2025-01-01';
|
||
```
|
||
|
||
### S3
|
||
```
|
||
Bucket : nouvel-espace-paie
|
||
Dossier : virements-salaires/{org_id}/
|
||
Fichier : {transfer_id}-{timestamp}.pdf
|
||
```
|
||
|
||
## ⚠️ Points d'attention
|
||
|
||
1. **Permissions Staff**
|
||
- Seuls les utilisateurs avec `is_staff = true` peuvent accéder
|
||
|
||
2. **Template PDFMonkey**
|
||
- ID template : `F4BCB5FF-1AB1-4CEE-B57F-82A6B9893E9E`
|
||
- Doit correspondre au format de payload attendu
|
||
|
||
3. **Contrats sans IBAN**
|
||
- Vérifier que tous les contrats ont un IBAN avant génération
|
||
- Sinon, le PDF contiendra des IBANs vides
|
||
|
||
4. **Timeout de génération**
|
||
- Par défaut : 15 tentatives × 3 secondes = 45 secondes max
|
||
- Ajustable dans `generate-pdf/route.ts`
|
||
|
||
5. **Coût S3**
|
||
- Chaque génération crée un nouveau fichier
|
||
- Penser à nettoyer les anciens fichiers si nécessaire
|
||
|
||
## 📚 Documentation détaillée
|
||
|
||
- **Fonctionnalité complète** : `VIREMENTS_SALAIRES_STAFF_FEATURE.md`
|
||
- **Guide de test** : `VIREMENTS_SALAIRES_TEST_GUIDE.md`
|
||
- **Requêtes SQL** : `VIREMENTS_SALAIRES_SQL_QUERIES.md`
|
||
|
||
## 🐛 Résolution de problèmes
|
||
|
||
| Problème | Solution |
|
||
|----------|----------|
|
||
| PDF ne se génère pas | Vérifier `PDFMONKEY_API_KEY` et le template ID |
|
||
| Contrats manquants | Vérifier que `payment_date` correspond au mois |
|
||
| Erreur S3 | Vérifier les credentials AWS |
|
||
| Timeout | Augmenter `maxAttempts` dans generate-pdf/route.ts |
|
||
| Accès refusé | Vérifier `is_staff = true` pour l'utilisateur |
|
||
|
||
## 🎉 Résumé
|
||
|
||
Cette implémentation permet aux utilisateurs Staff de :
|
||
- ✅ Créer des enregistrements de virements de salaires
|
||
- ✅ Générer automatiquement les feuilles d'appel en PDF
|
||
- ✅ Suivre l'état de chaque virement (PDF généré, notifications, etc.)
|
||
- ✅ Avoir une interface complète de gestion
|
||
|
||
Le tout intégré dans l'interface existante avec :
|
||
- Réactivité (Supabase Realtime)
|
||
- Sécurité (authentification Staff)
|
||
- Fiabilité (polling, gestion d'erreurs)
|
||
- Documentation complète
|
||
|
||
## 📞 Support
|
||
|
||
En cas de problème, consulter :
|
||
1. Les logs serveur Next.js
|
||
2. La console JavaScript du navigateur
|
||
3. Les logs PDFMonkey (via leur dashboard)
|
||
4. Les logs AWS S3
|
||
|
||
Pour des questions spécifiques, se référer aux fichiers de documentation détaillée.
|