espace-paie-odentas/DOCUSEAL_SIGNATURE_PREFILL.md

# Pré-remplissage de la Signature Employeur - DocuSeal

## Date: 14 octobre 2025

## Fonctionnalité

Cette fonctionnalité permet de **pré-remplir automatiquement la signature de l'employeur** lors de la création d'une signature électronique via DocuSeal.

### Principe

1. La signature de l'employeur est stockée en **base64** dans la table `organization_details` (colonne `signature_b64`)
2. Lors de la création d'une signature électronique, l'API récupère cette signature
3. DocuSeal pré-remplit le champ de signature avec cette image
4. L'employeur peut :
   - Utiliser la signature pré-remplie (gain de temps)
   - Ou la remplacer par une nouvelle signature

## Base de données

### Table: `organization_details`

Nouvelle colonne ajoutée :
```sql
ALTER TABLE organization_details 
ADD COLUMN signature_b64 TEXT;
```

**Format attendu :**
- Type: `TEXT`
- Contenu: Image de signature encodée en base64
- Format acceptés par DocuSeal :
  - Base64 encodée (ex: `data:image/png;base64,iVBORw0KG...`)
  - URL publique d'une image
  - Texte brut (sera rendu avec une police standard)

### Comment remplir la signature

1. **Via l'interface d'administration** (à implémenter)
2. **Via SQL directement** :
```sql
UPDATE organization_details 
SET signature_b64 = 'data:image/png;base64,iVBORw0KGgoAAAANS...'
WHERE org_id = 'votre-org-id';
```

## Modifications techniques

### 1. API DocuSeal Signature (`/app/api/docuseal-signature/route.ts`)

**Ajout du paramètre `orgId`** :
```typescript
const {
  // ... autres paramètres
  orgId = null // ID de l'organisation pour récupérer la signature
} = data;
```

**Récupération de la signature** :
```typescript
let employerSignatureB64 = null;
if (orgId) {
  const { data: orgDetails } = await supabase
    .from('organization_details')
    .select('signature_b64')
    .eq('org_id', orgId)
    .maybeSingle();
  
  if (orgDetails?.signature_b64) {
    employerSignatureB64 = orgDetails.signature_b64;
  }
}
```

**Pré-remplissage dans DocuSeal** :
```typescript
submitters: [
  { 
    role: 'Employeur', 
    email: employerEmail,
    metadata: {
      'allow-typed-signature': false,
      ...(employerSignatureB64 && {
        'signature': employerSignatureB64  // data-signature pour pré-remplir
      })
    }
  }
]
```

### 2. API Bulk E-Sign (`/app/api/staff/contracts/bulk-esign/route.ts`)

Ajout de `orgId` dans les données envoyées :
```typescript
const signatureData = {
  // ... autres champs
  orgId: contract.org_id // Passer l'org_id pour récupérer la signature
};
```

### 3. Contract Editor (`/components/staff/contracts/ContractEditor.tsx`)

Ajout de `orgId` dans les données de signature individuelle :
```typescript
const signatureData = {
  // ... autres champs
  orgId: contract.org_id // Passer l'org_id pour récupérer la signature
};
```

## Points d'application

La signature pré-remplie fonctionne pour :

1. ✅ **Signature individuelle** depuis `/staff/contrats/[id]`
2. ✅ **Signature groupée** depuis `/staff/contrats` (sélection multiple)

## Comportement utilisateur

### Pour l'employeur :

1. **Si une signature est enregistrée** :
   - Le champ de signature s'affiche avec la signature pré-remplie
   - L'employeur peut la valider directement (1 clic)
   - Ou la remplacer en dessinant/uploadant une nouvelle signature

2. **Si aucune signature n'est enregistrée** :
   - Comportement normal : l'employeur doit créer sa signature
   - Options : Dessiner ou Uploader une image
   - ❌ Saisie au clavier désactivée

### Pour le salarié :

- Pas de pré-remplissage (chaque salarié signe manuellement)
- Options : Dessiner ou Uploader une image
- ❌ Saisie au clavier désactivée

## Avantages

✅ **Gain de temps** : L'employeur n'a pas besoin de redessiner à chaque contrat
✅ **Cohérence** : Même signature sur tous les contrats de l'organisation
✅ **Flexibilité** : Possibilité de remplacer la signature si nécessaire
✅ **Sécurité** : Signature stockée de manière centralisée et sécurisée

## Migration SQL

```sql
-- Ajouter la colonne signature_b64 si elle n'existe pas
ALTER TABLE organization_details 
ADD COLUMN IF NOT EXISTS signature_b64 TEXT;

-- Créer un index pour les recherches
CREATE INDEX IF NOT EXISTS idx_organization_details_signature 
ON organization_details(org_id) 
WHERE signature_b64 IS NOT NULL;
```

## Test

### Prérequis

1. **Ajouter une signature dans la base** :
```sql
UPDATE organization_details 
SET signature_b64 = 'data:image/png;base64,iVBORw0KG...'
WHERE org_id = 'VOTRE_ORG_ID';
```

2. **Créer une signature électronique** pour un contrat de cette organisation

### Processus de test

1. **Depuis la page du contrat** (`/contrats/[id]`) :
   - Ouvrir un contrat appartenant à une organisation avec signature_b64
   - Cliquer sur "Voir signature" ou accéder à la signature électronique
   
2. **Vérification** :
   - La signature de l'employeur devrait être pré-remplie
   - L'employeur peut la valider directement ou la remplacer
   - Le salarié n'a pas de pré-remplissage (signature manuelle requise)

### Fonctionnement technique

1. **API `/api/contrats/[id]/signature`** :
   - Récupère le contrat avec l'org_id
   - Récupère la signature_b64 depuis organization_details
   - Retourne les données avec la signature

2. **Page `/contrats/[id]`** :
   - Récupère les données via l'API
   - Stocke la signature dans sessionStorage
   - Injecte `data-signature` dans le composant `<docuseal-form>`

3. **Composant `<docuseal-form>`** :
   - Lit la signature depuis sessionStorage
   - Ajoute l'attribut `data-signature` dynamiquement
   - DocuSeal pré-remplit le champ de signature

### Points d'application actuels

✅ **Page de détail du contrat** (`/contrats/[id]`) - IMPLÉMENTÉ
⏳ **Page signatures électroniques** (`/signatures-electroniques`) - À IMPLÉMENTER
⏳ **Signature groupée** (`/staff/contrats`) - À IMPLÉMENTER (nécessite modification de l'API bulk-esign)

## Références

- Documentation DocuSeal `data-signature` : https://docs.docuseal.co/api
- Format : Allows pre-filling signature fields
- Types acceptés :
  - Base64 encoded image string
  - Public URL to an image  
  - Plain text (rendered with standard font)

## TODO (Améliorations futures)

- [ ] Interface d'administration pour uploader/gérer la signature
- [ ] Validation du format base64
- [ ] Prévisualisation de la signature dans l'interface
- [ ] Historique des signatures utilisées
- [ ] Support de plusieurs signatures par organisation (différents signataires)