espace-paie-odentas/VIREMENTS_SALAIRES_SIGNATURES_STAFF.md

# Signatures électroniques sur la page Virements Salaires (Staff)

## 📋 Vue d'ensemble

Cette fonctionnalité permet aux utilisateurs **staff** de visualiser les signatures électroniques en attente pour une organisation spécifique directement depuis la page **Virements salaires**.

## ✨ Fonctionnalités

### Pour les utilisateurs Staff uniquement

1. **Menu déroulant des organisations**
   - Affiché uniquement pour les utilisateurs staff
   - Liste toutes les organisations disponibles
   - Permet de sélectionner une organisation pour voir ses données

2. **Section Signatures électroniques**
   - Affichée uniquement quand un staff a sélectionné une organisation
   - Liste tous les contrats en attente de signature pour l'organisation
   - Informations affichées :
     - Référence du contrat
     - Nom du salarié
     - Profession
     - Date de début
     - Statut signature employeur (✓ Signé / ⏳ En attente)
     - Statut signature salarié (✓ Signé / ⏳ En attente)
     - Bouton "Voir" pour accéder au lien de signature DocuSeal

## 🔧 Implémentation technique

### Fichiers modifiés

#### 1. `/app/(app)/virements-salaires/page.tsx`

**Nouveaux hooks ajoutés :**
```typescript
// Hook pour récupérer les signatures électroniques d'une organisation
function useSignatures(selectedOrgId?: string)
```

**Nouvelles fonctionnalités :**
- Menu déroulant de sélection d'organisation (visible uniquement pour les staff)
- Section d'affichage des signatures électroniques avec tableau détaillé
- Icônes ajoutées : `FileSignature`, `Eye`

**État local :**
```typescript
const [selectedOrgId, setSelectedOrgId] = useState<string>("");
```

#### 2. `/app/api/signatures-electroniques/contrats/route.ts`

**Modifications :**
- Ajout du support du paramètre `org_id` en query string
- Les utilisateurs staff peuvent passer un `org_id` pour filtrer les signatures d'une organisation spécifique
- Champs supplémentaires retournés :
  - `employee_first_name`
  - `employee_last_name`
  - `role` (profession)
  - `start_date`
  - `signature_employeur` (booléen)
  - `signature_salarie` (booléen)

**Exemple d'appel API :**
```typescript
GET /api/signatures-electroniques/contrats?org_id=<organization_id>
```

### API utilisées

#### 1. GET `/api/staff/organizations`
- Liste toutes les organisations
- Accessible uniquement aux staff
- Retourne : `{ organizations: [{ id, name, structure_api }] }`

#### 2. GET `/api/signatures-electroniques/contrats?org_id=<org_id>`
- Liste les signatures électroniques en attente
- Filtre par organisation si `org_id` fourni
- Accessible aux staff et membres d'organisation
- Retourne : `{ records: [...] }`

## 🎨 Interface utilisateur

### Menu déroulant des organisations
```tsx
<select value={selectedOrgId} onChange={(e) => setSelectedOrgId(e.target.value)}>
  <option value="">Toutes les organisations</option>
  {organizations.map(org => (
    <option key={org.id} value={org.id}>{org.name}</option>
  ))}
</select>
```

### Tableau des signatures
| Colonne | Description |
|---------|-------------|
| Référence | Référence du contrat |
| Salarié·e | Nom complet du salarié |
| Profession | Fonction/rôle du salarié |
| Date début | Date de début du contrat |
| Statut employeur | Badge ✓ Signé ou ⏳ En attente |
| Statut salarié | Badge ✓ Signé ou ⏳ En attente |
| Actions | Bouton "Voir" avec icône Eye |

### États des badges
- **✓ Signé** : Badge vert (`bg-emerald-100 text-emerald-800`)
- **⏳ En attente** : Badge orange (`bg-amber-100 text-amber-800`)

## 🔐 Sécurité et permissions

### Vérifications côté client
- Le menu déroulant et la section signatures ne s'affichent que si `userInfo?.isStaff === true`
- La section signatures ne s'affiche que si une organisation est sélectionnée

### Vérifications côté serveur (API)
- Vérification du statut staff via la table `staff_users`
- Les utilisateurs non-staff ne peuvent voir que les signatures de leur propre organisation
- Les staff peuvent voir les signatures de n'importe quelle organisation

## 📊 Filtrage des signatures

L'API filtre automatiquement les contrats selon les critères suivants :
- `etat_de_la_demande` = "Traitée" (ou variantes)
- Contrats en attente de signature employeur : `contrat_signe_par_employeur` = "non"
- Contrats en attente de signature salarié : `contrat_signe` = "non" + `contrat_signe_par_employeur` = "oui"

## 🚀 Utilisation

### Pour un utilisateur Staff

1. Se connecter avec un compte staff
2. Accéder à la page `/virements-salaires`
3. Sélectionner une organisation dans le menu déroulant en haut de la page
4. La section "Signatures électroniques" apparaît automatiquement sous les virements
5. Consulter les signatures en attente
6. Cliquer sur "Voir" pour accéder au lien DocuSeal

### Cas d'usage

- **Suivi global** : Les staff peuvent surveiller l'état des signatures pour toutes les organisations
- **Support client** : Identifier rapidement les contrats bloqués en attente de signature
- **Vérification** : S'assurer que les signatures sont en cours avant d'effectuer les virements

## 🔄 Synchronisation des données

- Les données des signatures sont chargées automatiquement lors de la sélection d'une organisation
- Le hook `useSignatures` utilise React Query avec un `staleTime` de 15 secondes
- Les données sont mises en cache pour éviter les appels API inutiles

## 📝 Types TypeScript

```typescript
type SignatureRecord = {
  id: string;
  fields: {
    reference: string;
    employee_first_name: string;
    employee_last_name: string;
    role: string; // Profession
    start_date: string;
    signature_employeur: boolean;
    signature_salarie: boolean;
    signature_link?: string;
  };
};
```

## ⚠️ Points d'attention

1. **Performance** : La liste des organisations est chargée uniquement pour les staff
2. **Cache** : Les signatures sont mises en cache avec React Query
3. **Liens DocuSeal** : Le lien peut être absent si la signature n'a pas encore été initiée
4. **Format des données** : L'API retourne un format compatible avec l'ancien système Airtable

## 🐛 Débogage

### Console navigateur
```javascript
// Vérifier les données chargées
// Dans React Query Devtools, chercher les clés :
// - ["organizations"]
// - ["signatures-electroniques", selectedOrgId]
```

### Logs serveur
```
🔍 [signatures-electroniques] Requête pour scope: employeur, orgId: <org_id>
📊 [signatures-electroniques] Contrats trouvés: X
📋 [signatures-electroniques] Échantillon: [...]
```

## 🔮 Améliorations futures

- [ ] Ajouter un filtre par statut (tout / en attente employeur / en attente salarié)
- [ ] Ajouter une recherche par nom de salarié ou référence
- [ ] Afficher le nombre de signatures en attente dans le titre de section
- [ ] Ajouter un bouton de rafraîchissement manuel
- [ ] Permettre l'envoi de relances depuis cette page
- [ ] Afficher la date de création du contrat
- [ ] Ajouter un tri par date/référence/salarié

## 📚 Documentation associée

- [SIGNATURE_SALARIE_FEATURE.md](./SIGNATURE_SALARIE_FEATURE.md) - Documentation des signatures salarié
- [DOCUSEAL_ENV_VARIABLES.md](./DOCUSEAL_ENV_VARIABLES.md) - Variables d'environnement DocuSeal
- [STAFF_MAINTENANCE_ACCESS_GUIDE.md](./STAFF_MAINTENANCE_ACCESS_GUIDE.md) - Guide d'accès staff