espace-paie-odentas/UPLOAD_MANUAL_SIGNED_CONTRACT.md

Upload Manuel du Contrat Signé - Guide

Vue d'ensemble

Cette fonctionnalité permet au staff d'uploader manuellement le PDF d'un contrat signé lorsqu'il a été reçu par un moyen externe (email, courrier, etc.) au lieu de passer par le processus Docuseal.

Comment utiliser

Accès

1. Aller sur la page staff/contrats/[id] d'un contrat
2. Dans la section Documents, cliquer sur le bouton "Ajouter le contrat signé manuellement"

Upload

1. Une modale s'ouvre avec une zone de dépôt de fichier
2. Cliquer sur la zone ou glisser-déposer un fichier PDF
3. Vérifications automatiques :
   • Type de fichier : doit être un PDF
   • Taille maximum : 10 Mo
4. Cliquer sur "Uploader"

Après l'upload

• Le PDF est stocké dans S3 à la clé : contracts/<org-slug>/<contract_number>.pdf
• Le champ contract_pdf_s3_key est mis à jour dans la base de données
• Le champ contrat_signe passe à "Oui"
• Le contrat apparaît dans la section Documents avec le même style qu'un contrat signé via Docuseal

Architecture technique

Fichiers créés

1. API Route : /app/api/staff/contrats/[id]/upload-signed-pdf/route.ts

• Méthode : POST
• Authentification : Staff uniquement
• Corps de la requête : FormData avec un champ file contenant le PDF
• Traitement :
  1. Vérification des droits staff
  2. Validation du type de fichier (application/pdf)
  3. Récupération de l'organisation pour obtenir l'api_name
  4. Upload dans S3 avec la clé contracts/<org-slug>/<contract_number>.pdf
  5. Mise à jour du contrat : contract_pdf_s3_key et contrat_signe = "Oui"

2. Composant : /components/staff/contracts/ManualSignedContractUpload.tsx

• Modal avec zone de dépôt de fichier
• Validation côté client (type, taille)
• États de chargement et de succès
• Callback onSuccess pour rafraîchir les données après upload

3. Modifications : /components/staff/contracts/ContractEditor.tsx

• Import du composant ManualSignedContractUpload et de l'icône Upload
• Ajout du state isUploadModalOpen
• Ajout du bouton d'upload dans la section Documents
• Invalidation de la query signed-contract-pdf après upload pour rafraîchir automatiquement
• Modification de la condition enabled de la query pour toujours vérifier l'existence d'un contrat signé

Flux de données

1. Utilisateur clique sur "Ajouter le contrat signé manuellement"
   ↓
2. Modal s'ouvre → Sélection du fichier PDF
   ↓
3. Click sur "Uploader" → POST /api/staff/contrats/[id]/upload-signed-pdf
   ↓
4. API vérifie les droits → Récupère l'organization → Upload S3
   ↓
5. Mise à jour BDD (contract_pdf_s3_key, contrat_signe)
   ↓
6. Success → Invalidation de la query → Rafraîchissement automatique
   ↓
7. Le contrat signé apparaît dans la section Documents

Stockage S3

Le PDF uploadé est stocké exactement au même endroit que s'il avait été signé via Docuseal :

• Bucket : odentas-docs (ou valeur de AWS_S3_BUCKET)
• Clé : contracts/<org-slug>/<contract_number>.pdf
• ACL : Private
• ContentType : application/pdf

Cela garantit que :

• L'API /api/staff/contrats/[id]/signed-pdf fonctionne de la même manière
• Les emails de notification peuvent récupérer le PDF
• La logique existante n'est pas perturbée

Cas d'usage

Quand utiliser cette fonctionnalité ?

1. Contrat signé par courrier : Le salarié ou l'employeur a imprimé, signé et renvoyé le contrat par courrier
2. Contrat signé par email : Le PDF signé a été renvoyé par email au lieu de passer par Docuseal
3. Problème technique Docuseal : En cas de dysfonctionnement de Docuseal, permet de continuer le processus
4. Migration de données : Upload de contrats historiques déjà signés

Points d'attention

• Le PDF doit être déjà signé par les deux parties
• L'upload marque automatiquement contrat_signe = "Oui"
• Si un contrat signé existe déjà, il sera remplacé
• La limite de 10 Mo est suffisante pour la plupart des contrats (quelques pages)

Sécurité

• Accès réservé au staff uniquement (vérification via staff_users.is_staff)
• Validation stricte du type MIME (application/pdf)
• Upload direct vers S3 avec ACL Private
• Pas d'exécution de code du PDF (simple stockage)

Tests

Pour tester la fonctionnalité :

1. Se connecter en tant que staff
2. Aller sur un contrat existant (ex: /staff/contrats/123)
3. Cliquer sur "Ajouter le contrat signé manuellement"
4. Uploader un PDF de test
5. Vérifier que :
   • Le PDF apparaît dans la section Documents
   • Le statut du contrat passe à "signé"
   • Le lien "Contrat CDDU signé" ouvre le bon fichier
   • Le champ contract_pdf_s3_key est bien rempli dans la BDD

Notes techniques

• Utilise @aws-sdk/client-s3 pour l'upload (PutObjectCommand)
• Utilise useQueryClient pour invalider les queries React Query
• Le modal utilise les composants shadcn/ui (Dialog)
• Compatible avec la logique existante de récupération des contrats signés