# Ajout du Numéro d'Appel pour les Virements de Salaires

## 📋 Vue d'ensemble

Cette fonctionnalité ajoute un champ **numéro d'appel** (`num_appel`) personnalisable pour chaque virement de salaire. Ce numéro est saisi manuellement lors de la création/modification d'un virement et est utilisé pour générer la référence du virement.

## 🎯 Format de la Référence

**Format**: `CODE_EMPLOYEUR-NUMERO_APPEL`

**Exemple**: `DEMO-00001`

- `CODE_EMPLOYEUR` : Code employeur issu de `organization_details.code_employeur`
- `NUMERO_APPEL` : Numéro saisi manuellement par l'utilisateur (ex: "00001")

## ✅ Modifications Apportées

### 1. Base de Données
La colonne `num_appel` existe dans la table `salary_transfers` (type `text`, nullable).

### 2. Interface Utilisateur (`components/staff/SalaryTransfersGrid.tsx`)

#### Type `SalaryTransfer`
Ajout du champ :
```typescript
num_appel?: string | null;
```

#### Formulaire de Création
- Nouveau champ "Numéro d'appel" (obligatoire)
- Placeholder: "Ex: 00001"
- Texte d'aide : "Ce numéro sera utilisé pour générer la référence du virement (code_employeur-numéro)"
- Validation : le champ doit être rempli pour créer un virement

#### Formulaire de Modification
- Champ "Numéro d'appel" modifiable
- Même format et présentation que le formulaire de création

#### Tableau des Virements
- Nouvelle colonne "N° Appel" affichée entre "Période" et "Mode"
- Affichage en police monospace pour une meilleure lisibilité

#### Modal de Détails
- Ajout d'une carte "N° d'appel" dans la grille d'informations
- Affichage en police monospace

### 3. Génération PDF (`app/api/staff/virements-salaires/generate-pdf/route.ts`)

#### Référence de Virement
Modification de la logique de génération :

```typescript
// Ancien format
const transferReference = `${organization.code}-${salaryTransfer.num_appel}-${formatMonthPeriod(period)}`;

// Nouveau format
const codeEmployeur = orgDetails?.code_employeur || organization.code || "ORG";
const transferReference = `${codeEmployeur}-${salaryTransfer.num_appel}`;
```

**Changements** :
- Utilise `organization_details.code_employeur` en priorité
- Fallback sur `organization.code` si `code_employeur` n'existe pas
- Ne contient plus la période dans la référence
- Format simplifié : `CODE-NUMERO`

#### Payload PDFMonkey
Le numéro d'appel est inclus dans le payload :
```typescript
{
  callsheet_number: salaryTransfer.num_appel || "00000",
  transfer_reference: transferReference,
  // ... autres champs
}
```

### 4. Logs de Débogage

Des logs détaillés ont été ajoutés pour faciliter le diagnostic des problèmes de récupération des paies :

```typescript
console.log("[generate-pdf] Payslips query result:", {
  error: payslipsError,
  count: payslips?.length || 0,
  sample: payslips?.[0] ? {
    id: payslips[0].id,
    net_amount: payslips[0].net_amount,
    has_contract: !!payslips[0].cddu_contracts,
    has_salarie: !!payslips[0].cddu_contracts?.salaries
  } : null
});

// Log details about contracts
const withContracts = payslips.filter(p => p.cddu_contracts).length;
const withSalaries = payslips.filter(p => p.cddu_contracts?.salaries).length;
console.log("[generate-pdf] Payslips with contracts:", withContracts);
console.log("[generate-pdf] Payslips with salaries:", withSalaries);
```

**Informations loggées** :
- Nombre total de paies trouvées
- Exemple de paie avec détails (ID, montant net, présence contrat/salarié)
- Nombre de paies avec contrats liés
- Nombre de paies avec salarié lié
- Paramètres de la requête (org_id, period_month)
- Première paie complète en JSON pour debug approfondi

## 📝 Exemple d'Utilisation

### Création d'un Virement

1. **Accéder** : Staff → Virements de Salaires → Bouton "Créer"
2. **Remplir** :
   - Organisation : "ACME Productions"
   - Période : "2025-01"
   - Libellé : "Janvier 2025"
   - Date d'échéance : "2025-01-15"
   - Mode : "SEPA"
   - **Numéro d'appel** : "00001" ← **Nouveau champ**
   - Total Net : (optionnel)
   - Notes : (optionnel)

3. **Résultat** :
   - Un virement est créé avec `num_appel = "00001"`
   - Lors de la génération PDF, la référence sera : `DEMO-00001`
     (si `code_employeur` de l'organisation est "DEMO")

### Modification du Numéro

1. **Ouvrir** : Cliquer sur un virement dans le tableau
2. **Modifier** : Cliquer sur "Modifier"
3. **Changer** : Modifier le champ "Numéro d'appel"
4. **Enregistrer** : Cliquer sur "Enregistrer"

## 🔍 Points Importants

### Validation
- Le numéro d'appel est **obligatoire** lors de la création
- Pas de contrainte de format (libre saisie)
- Recommandé : utiliser un format numérique avec zéros de tête (ex: "00001", "00042")

### Génération PDF
- Le numéro d'appel est utilisé immédiatement lors de la génération
- Si le champ est vide, utilise "00000" par défaut
- La référence est calculée au moment de la génération (pas stockée en base)

### Code Employeur
Priorité de recherche pour le code employeur :
1. `organization_details.code_employeur` (prioritaire)
2. `organization.code` (fallback)
3. `"ORG"` (fallback final si aucun code n'existe)

## 🎨 Interface Utilisateur

### Affichage dans le Tableau
```
| Période       | N° Appel | Mode | ... |
|---------------|----------|------|-----|
| Janvier 2025  | 00001    | SEPA | ... |
| Février 2025  | 00002    | SEPA | ... |
```

### Modal de Détails
```
┌─────────────────┬─────────────────┐
│ Période         │ N° d'appel      │
│ Janvier 2025    │ 00001           │
├─────────────────┼─────────────────┤
│ Mode            │ Échéance        │
│ SEPA            │ 15/01/2025      │
└─────────────────┴─────────────────┘
```

## 🐛 Dépannage

### Le numéro d'appel n'apparaît pas
- Vérifier que la colonne `num_appel` existe dans la table `salary_transfers`
- Vérifier que la valeur a bien été enregistrée en base
- Recharger la page

### Aucune paie n'apparaît lors de la génération PDF
1. **Consulter les logs serveur** (terminal où Next.js tourne)
2. **Vérifier les logs** :
   ```
   [generate-pdf] Payslips query result: { error: null, count: 0, ... }
   [generate-pdf] No payslips found for this period!
   [generate-pdf] Query params: { organization_id: "...", period_month: "2025-01-01" }
   ```
3. **Vérifier dans Supabase** :
   - Les paies existent pour cette organisation et cette période
   - Le champ `period_month` est au format `YYYY-MM-01` (ex: `2025-01-01`)
   - Le champ `organization_id` correspond bien à l'organisation du virement
4. **Vérifier les relations** :
   - Les paies ont un `contract_id` valide
   - Les contrats existent dans `cddu_contracts`
   - Les contrats ont un `employee_id` valide
   - Les salariés existent dans `salaries`

### Les informations des salariés sont manquantes
Vérifier dans les logs :
```
[generate-pdf] Payslips with contracts: X
[generate-pdf] Payslips with salaries: Y
```
- Si X < nombre total de paies : certaines paies n'ont pas de contrat lié
- Si Y < X : certains contrats n'ont pas de salarié lié
- Vérifier les clés étrangères dans la base de données

### La référence est incorrecte
- Vérifier que `organization_details.code_employeur` existe
- Vérifier la console pour les logs de génération PDF
- Format attendu : `CODE-NUMERO` sans espaces

### Erreur lors de la création
- Vérifier que le numéro d'appel est rempli
- Le champ ne doit pas être vide (validation côté client)

## 📚 Fichiers Modifiés

1. **components/staff/SalaryTransfersGrid.tsx**
   - Changement : `callsheet_number` → `num_appel`
   - Ajout du champ dans le type `SalaryTransfer`
   - Ajout du champ dans `createForm`
   - Ajout du champ dans les formulaires (création/édition)
   - Ajout de la colonne dans le tableau
   - Ajout de l'affichage dans la modal de détails
   - Ajout de la validation

2. **app/api/staff/virements-salaires/generate-pdf/route.ts**
   - Changement : `callsheet_number` → `num_appel`
   - Modification de la génération de `transfer_reference`
   - Utilisation de `code_employeur` au lieu de `organization.code`
   - Simplification du format (suppression de la période)
   - **Ajout de logs détaillés** pour le débogage de la récupération des paies :
     * Log du résultat de la requête payslips
     * Log du nombre de paies avec contrats/salariés
     * Log de la première paie en JSON
     * Log des paramètres de requête si aucune paie trouvée
     * Log d'avertissement si aucune paie

## ✨ Améliorations Futures Possibles

- [ ] Auto-incrémentation du numéro d'appel par organisation
- [ ] Validation du format (ex: uniquement numérique)
- [ ] Vérification d'unicité du numéro par organisation
- [ ] Import/export avec numéro d'appel
- [ ] Recherche/filtre par numéro d'appel
- [ ] Historique des modifications du numéro

## 📅 Date de Mise en Place
13 octobre 2025