Système d'Export Centralisé

Vue d'ensemble

Le système d'export a été complètement refactorisé pour centraliser tous les exports de l'application et supporter plusieurs formats (PDF, Word/DOCX, CSV, Excel) pour tous les types de données.

✅ Migration complète terminée : Tous les exports utilisent maintenant le système unifié ExportFormatDialog / EntityExportDialog pour une expérience utilisateur cohérente.

Architecture détaillée : Voir EXPORT_STORAGE_ARCHITECTURE.md pour la documentation technique complète (sécurité, cleanup, monitoring, file_objects unifiés).

Sécurité et Performance (2026-01)

Contrôle d'accès

Signed URLs : Vérification d'appartenance via StorageAccessService avant génération
FileObjects : Vérification d'organisation pour tous les accès
Rate Limiting : 10 req/min (sync), 5 req/min (async)

Cleanup automatique

Export files : Suppression quotidienne des fichiers > 24h
Orphaned files : Nettoyage hebdomadaire/mensuel des fichiers orphelins
Avatars/Logos : Suppression automatique lors du remplacement

Monitoring

Métriques Prometheus pour exports et cleanup
Endpoint /api/metrics pour scraping

Formats Supportés

PDF

Utilisation : Impression et partage
Content-Type : application/pdf
Extension : .pdf
Disponible pour : Tous les exports

Word (DOCX)

Utilisation : Édition et modification
Content-Type : application/vnd.openxmlformats-officedocument.wordprocessingml.document
Extension : .docx
Disponible pour : Tous les exports

CSV

Utilisation : Tableurs et analyse de données
Content-Type : text/csv
Extension : .csv
Disponible pour : Tous les exports (sauf "all" entity)

Excel (XLSX)

Utilisation : Analyse de données avancée
Content-Type : application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Extension : .xlsx
Disponible pour : Tous les exports

JSON

Utilisation : Sauvegarde et accès programmatique
Content-Type : application/json
Extension : .json
Disponible pour : Tous les exports

Architecture

Backend

Service Centralisé : `ExportService`

Fichier : backend/src/export/export.service.ts
Responsabilités :
- Export de sessions, contacts, quotes, invoices
- Génération de tous les formats (CSV, DOCX, Excel, JSON, PDF)
- Gestion centralisée de la logique d'export

Contrôleur : `ExportController`

Fichier : backend/src/export/export.controller.ts
Endpoint : GET /api/export?entity={entity}&format={format}&fields={fields}
Entités supportées : sessions, contacts, quotes, invoices, all
Paramètres :
- entity (required) : Type de données à exporter
- format (required) : Format d'export (csv, excel, pdf, docx, json)
- fields (optional) : Liste de champs séparés par virgules (ex: id,title,email)

Frontend

Composant Réutilisable : `ExportFormatDialog`

Fichier : frontend/src/components/export/ExportFormatDialog.tsx
Utilisation : Dialog réutilisable pour sélectionner le format d'export
Props :
- availableFormats : Formats disponibles (optionnel, par défaut tous)
- onFormatSelect : Callback lors de la sélection
- onOpenChange : Gestion de l'état d'ouverture
- open : État d'ouverture
- titleKey / descriptionKey : Clés de traduction personnalisables

Exports Spécifiques

1. Roadmap Export (Sessions)

Backend :

Endpoint : GET /api/sessions/:id/roadmap?format={format}
Formats : pdf, docx
Service : SessionRoadmapService

Frontend :

Composant : RoadmapExportDialog (utilise ExportFormatDialog)
Fichier : frontend/src/pages/sessions/SessionViewPage/components/RoadmapExportDialog.tsx

2. Conversation Export (Agent)

Backend :

Endpoint : GET /api/agent/conversations/:conversationId/export?format={format}
Formats : pdf, docx, csv, excel, txt
Service : AgentExportService

Frontend :

Fonction : exportConversation(format)
Fichier : frontend/src/components/search/agent/exportConversation.ts

3. Quotes Export

Backend :

Endpoint : GET /api/quotes/:id/export?format={format}
Formats : pdf, docx
Service : QuotesController (utilise PdfService et conversion HTML→Word)

Frontend :

Hook : useQuoteActions avec onExportClick callback
Composant : EntityExportDialog via useEntityExport
Client : getQuoteExportUrl(quoteId, format)
Status : ✅ Migré vers ExportFormatDialog (PDF, DOCX)

4. Invoices Export

Backend :

Endpoint : GET /api/invoices/:id/export?format={format}
Formats : pdf, docx
Service : InvoicesController (utilise PdfService et conversion HTML→Word)

Frontend :

Hook : useInvoiceActions avec onExportClick callback
Composant : EntityExportDialog via useEntityExport
Client : getInvoiceExportUrl(invoiceId, format)
Status : ✅ Migré vers ExportFormatDialog (PDF, DOCX)

5. Contracts Export

Backend :

Endpoint : GET /api/contracts/:id/pdf
Formats : pdf (DOCX à venir)
Service : ContractsController (utilise PdfService)

Frontend :

Hook : useContractActions avec onExportClick callback
Composant : EntityExportDialog via useEntityExport
Client : getContractExportUrl(contractId, format)
Status : ✅ Migré vers ExportFormatDialog (PDF uniquement pour l'instant)

6. Contract Templates Export

Backend :

Endpoint : GET /api/contract-templates/:id/export?format={format}
Formats : pdf, docx, csv, excel
Service : ContractTemplatesController (utilise PdfService et conversion HTML→Word)

Frontend :

Composant : EntityExportDialog via useEntityExport
Client : getContractTemplateExportUrl(templateId, format)
Status : ✅ Migré vers ExportFormatDialog (PDF, DOCX, CSV, Excel)

6. Analytics Export

Backend :

Endpoints :
- GET /api/analytics/pdf?startDate={date}&endDate={date} - Export PDF
- GET /api/analytics/excel?startDate={date}&endDate={date} - Export Excel
- GET /api/analytics/word?startDate={date}&endDate={date} - Export Word
Formats : pdf, excel, docx
Services :
- AnalyticsPdfService - Génération PDF
- AnalyticsExportService - Génération Excel et Word (utilise Python services)

Frontend :

Composant : DateRangeSelector avec ExportFormatDialog
Fichier : frontend/src/pages/analytics/AnalyticsPage/AnalyticsPage/components/DateRangeSelector.tsx
Hook : useAnalyticsPage avec handleExport(format, startDate?, endDate?)
Client : getAnalyticsPdfUrl, getAnalyticsExcelUrl, getAnalyticsWordUrl
Status : ✅ Migré vers ExportFormatDialog avec sélection de date

7. AI Report Export (Comprehensive Analytics Report)

Backend :

Endpoints :
- POST /api/ai-assistant/report/pdf - Export PDF
- POST /api/ai-assistant/report/docx - Export Word
Formats : pdf, docx
Service : AiAssistantService (utilise Python services)

Frontend :

Composant : AiReportGenerator avec ExportFormatDialog
Fichier : frontend/src/components/search/AiReportGenerator.tsx
Status : ✅ Migré vers ExportFormatDialog (remplace les boutons séparés PDF/DOCX)

9. Generic Data Export

Backend :

Endpoint : GET /api/export?entity={entity}&format={format}
Entités : sessions, contacts, quotes, invoices, all
Formats : csv, docx, excel, json, pdf
Service : ExportService

Frontend :

Composant : ExportButton (utilise ExportFormatDialog quand showDateRange=true)
Fichier : frontend/src/components/export/ExportButton.tsx
Status : ✅ Utilise ExportFormatDialog pour exports avec date range

Conversion HTML → Word

Pour les exports qui génèrent du HTML (quotes, invoices, contract templates), une méthode utilitaire htmlToWordDocument a été créée qui :

Parse le HTML avec cheerio
Extrait les éléments structurés (titres, paragraphes, tableaux)
Convertit en document Word avec docx
Préserve la structure et le formatage

Limitations :

Conversion simplifiée (pas de styles complexes)
Pour une meilleure qualité, considérer une bibliothèque dédiée HTML→DOCX

Traductions

Toutes les traductions sont centralisées sous export.formats.* :

{
  "export": {
    "title": "Exporter",
    "description": "Choisissez le format d'export",
    "formats": {
      "pdf": { "title": "PDF", "description": "..." },
      "docx": { "title": "Word (DOCX)", "description": "..." },
      "csv": { "title": "CSV", "description": "..." },
      "excel": { "title": "Excel (XLSX)", "description": "..." },
      "json": { "title": "JSON", "description": "..." }
    }
  }
}

Utilisation

Backend

// Export sessions as Word
const buffer = await exportService.exportSessions(
  userId,
  ExportFormatValues.DOCX,
);

Frontend

Utilisation avec ExportFormatDialog (pour exports avec date range)

import { ExportFormatDialog } from "@/components/export";

<ExportFormatDialog
  availableFormats={["pdf", "docx"]}
  onFormatSelect={(format) => handleExport(format)}
  onOpenChange={setOpen}
  open={isOpen}
  showDateRange
  titleKey="sessions.roadmap.export.title"
  descriptionKey="sessions.roadmap.export.description"
/>;

Utilisation avec EntityExportDialog (pour exports d'entités individuelles)

import { EntityExportDialog } from "@/components/export/EntityExportDialog";
import { useEntityExport } from "@/hooks/useEntityExport";

// Dans votre composant
const entityExport = useEntityExport({
  availableFormats: ["pdf", "docx"],
  entityName: "quote",
  getFilename: (id) => `quote_${id}.pdf`,
  onExport: async (format) => {
    return await getQuoteExportUrl(id, format);
  },
});

// Dans le JSX
<>
  {entityExport.dialog}
  <Button onClick={() => entityExport.openDialog(entityId)}>
    Export
  </Button>
</>

Fichiers Modifiés/Créés

Backend

backend/src/export/export.service.ts - Support DOCX, sélection de champs
backend/src/export/export.controller.ts - Support DOCX, paramètre fields
backend/src/export/README.md - Documentation complète
backend/src/import/ - Module d'import complet (CSV/Excel)
backend/src/scheduled-exports/ - Module d'exports planifiés
backend/src/export-templates/ - Module de templates d'export
backend/src/queue/processors/export.processor.ts - Support envoi par email
backend/src/queue/types/job-data.types.ts - Paramètres email et champs
backend/src/agent/agent-export.service.ts - Ajout PDF, CSV, Excel, TXT
backend/src/agent/agent.controller.ts - Endpoint unifié avec paramètre format
backend/src/agent/agent.module.ts - Ajout PdfModule pour support PDF
backend/src/quotes-invoices/quotes.controller.ts - Support Word, conversion HTML→Word
backend/src/quotes-invoices/invoices.controller.ts - Support Word, conversion HTML→Word
backend/src/contract-templates/contract-templates.controller.ts - Support Word, CSV, Excel
backend/src/contract-templates/contract-templates.module.ts - Ajout StorageModule pour uploads
infra/liquibase/changes/0139_create_scheduled_exports/ - Migration scheduled exports
infra/liquibase/changes/0140_create_export_templates/ - Migration export templates
openapi/components/export.yaml - Ajout format DOCX
backend/src/_generated/types.gen.ts - Types régénérés avec DOCX

Frontend

frontend/src/components/export/ExportFormatDialog.tsx - Composant centralisé pour sélection de format
frontend/src/components/export/EntityExportDialog.tsx - Composant pour exports d'entités individuelles
frontend/src/components/export/index.ts - Fichier d'export
frontend/src/hooks/useEntityExport.tsx - Hook pour gérer les exports d'entités
frontend/src/components/import/ImportContactsDialog.tsx - Composant d'import
frontend/src/components/import/index.ts - Fichier d'export import
frontend/src/client/import/useImport.ts - Hook d'import
frontend/src/client/quotes-invoices/useQuotesInvoices.ts - Ajout de getQuoteExportUrl et getInvoiceExportUrl
frontend/src/client/contracts/useContracts.ts - Ajout de getContractExportUrl et getContractTemplateExportUrl
frontend/src/pages/sessions/SessionViewPage/components/RoadmapExportDialog.tsx - Refactorisé
frontend/src/components/search/agent/exportConversation.ts - Fonction unifiée avec support multi-formats
frontend/src/hooks/useQuoteActions.tsx - Migré vers ExportFormatDialog avec onExportClick
frontend/src/hooks/useInvoiceActions.tsx - Migré vers ExportFormatDialog avec onExportClick
frontend/src/hooks/useContractActions.tsx - Migré vers ExportFormatDialog avec onExportClick
frontend/src/components/molecules/ExportButton.tsx - Migré vers ExportFormatDialog
frontend/src/i18n/locales/fr/translation.json - Traductions FR pour exports
frontend/src/i18n/locales/en/translation.json - Traductions EN pour exports

Nouvelles Fonctionnalités

Sélection Personnalisée des Champs

Vous pouvez maintenant sélectionner les champs spécifiques à exporter via le paramètre fields :

# Exporter uniquement id, title et status pour les sessions
GET /api/export?entity=sessions&format=csv&fields=id,title,status

# Exporter uniquement first_name, last_name et email pour les contacts
GET /api/export?entity=contacts&format=excel&fields=first_name,last_name,email

Exports Planifiés (Scheduled Exports)

Système complet pour planifier des exports automatiques avec récurrence :

Endpoints : GET/POST/PUT/DELETE /api/scheduled-exports
Fonctionnalités :
- Récurrence : daily, weekly, monthly, yearly
- Envoi automatique par email
- Gestion des statuts (PENDING, ACTIVE, PAUSED, CANCELLED)
- Sélection de champs personnalisée
Documentation : Voir docs/SCHEDULED_EXPORTS.md

Templates d'Export

Système de templates pré-configurés pour réutiliser des configurations d'export :

Endpoints : GET/POST/PUT/DELETE /api/export-templates
Fonctionnalités :
- Templates réutilisables avec champs sélectionnés
- Templates par défaut par entité/format
Documentation : Voir docs/EXPORT_TEMPLATES.md

Envoi d'Exports par Email

Les exports peuvent être envoyés automatiquement par email :

Support de pièces jointes
Sujet et message personnalisables
Intégré dans les scheduled exports

État des Migrations vers ExportFormatDialog

✅ Exports Migrés (utilisent ExportFormatDialog)

Analytics Export - DateRangeSelector avec PDF, Excel, Word
AI Report Export - AiReportGenerator avec PDF, Word
Roadmap Export - RoadmapExportDialog avec PDF, Word
Generic Data Export - ExportButton avec date range (tous formats)

✅ Exports Migrés (utilisent ExportFormatDialog)

Quotes Export (useQuoteActions)
- Fichier : frontend/src/hooks/useQuoteActions.tsx
- Backend supporte : PDF, DOCX
- Status : ✅ Migré vers ExportFormatDialog (PDF, DOCX)
- Composants mis à jour :
  - QuoteViewPage
  - QuotesListPage
  - ContactQuotesTab
  - QuotesInvoicesTab (SessionViewPage)
Invoices Export (useInvoiceActions)
- Fichier : frontend/src/hooks/useInvoiceActions.tsx
- Backend supporte : PDF, DOCX
- Status : ✅ Migré vers ExportFormatDialog (PDF, DOCX)
- Composants mis à jour :
  - InvoiceViewPage
  - InvoicesListPage
  - ContactInvoicesTab
  - QuotesInvoicesTab (SessionViewPage)
Contracts Export (useContractActions, ContractViewPage)
- Fichiers :
  - frontend/src/hooks/useContractActions.tsx
  - frontend/src/pages/contracts/ContractViewPage/ContractViewPage.tsx
- Backend supporte : PDF uniquement (pour l'instant)
- Status : ✅ Migré vers ExportFormatDialog (PDF uniquement)
Contract Templates Export
- Fichier : frontend/src/pages/contract-templates/ContractTemplatesPage/components/ContractTemplatesList.tsx
- Backend supporte : PDF, DOCX, CSV, Excel
- Status : ✅ Migré vers ExportFormatDialog (PDF, DOCX, CSV, Excel)
Quotes/Invoices Export (components/molecules/ExportButton.tsx)
- Fichier : frontend/src/components/molecules/ExportButton.tsx
- Formats : CSV, Excel, JSON
- Status : ✅ Migré vers ExportFormatDialog (CSV, Excel, JSON)

⏳ Exports Non Migrés (peuvent rester avec des boutons directs)

Les exports suivants peuvent rester avec des boutons PDF directs car ils sont destinés à un usage simple par les clients (client portal) :

Client Access Exports (ClientInvoicePage, ClientQuotePage, ClientContractPage)
- Fichiers :
  - frontend/src/pages/client/ClientInvoicePage/ClientInvoicePage.tsx
  - frontend/src/pages/client/ClientQuotePage/ClientQuotePage.tsx
  - frontend/src/pages/client/ClientContractPage/ClientContractPage.tsx
- Backend supporte : PDF uniquement (client access)
- Status : Bouton PDF direct (intentionnel - usage client simple)

Prochaines Étapes

✅ Système centralisé créé
✅ Formats multiples supportés
✅ Documentation complète
✅ Types TypeScript générés
✅ Backend complet pour tous les exports (quotes, invoices, contracts)
✅ Sélection personnalisée des champs
✅ Exports planifiés (scheduled exports)
✅ Templates d'export
✅ Envoi par email
✅ Analytics Export migré vers ExportFormatDialog (PDF, Excel, Word)
✅ AI Report Export migré vers ExportFormatDialog (PDF, Word)
✅ Quotes Export migré vers ExportFormatDialog (PDF, DOCX)
✅ Invoices Export migré vers ExportFormatDialog (PDF, DOCX)
✅ Contracts Export migré vers ExportFormatDialog (PDF)
✅ Contract Templates Export migré vers ExportFormatDialog (PDF, DOCX, CSV, Excel)
✅ Quotes/Invoices ExportButton (molecules) migré vers ExportFormatDialog (CSV, Excel, JSON)
✅ Contracts List Page migré vers ExportFormatDialog (PDF)
✅ Code mort supprimé (anciens handlers PDF directs)
✅ Documentation mise à jour (documentation interne)
⏳ Tests d'intégration (optionnel)

Notes Techniques

Conversion HTML→Word : Utilise cheerio pour parser et docx pour générer
Performance : Les exports sont asynchrones et gèrent de gros volumes
Stockage : Tous les fichiers sont uploadés sur R2 avec URLs signées
Sécurité : Tous les exports sont filtrés par owner_id

Vue d'ensemble​

Sécurité et Performance (2026-01)​

Contrôle d'accès​

Cleanup automatique​

Monitoring​

Formats Supportés​

PDF​

Word (DOCX)​

CSV​

Excel (XLSX)​

JSON​

Architecture​

Backend​

Service Centralisé : ExportService​

Contrôleur : ExportController​

Frontend​

Composant Réutilisable : ExportFormatDialog​

Exports Spécifiques​

1. Roadmap Export (Sessions)​

2. Conversation Export (Agent)​

3. Quotes Export​

4. Invoices Export​

5. Contracts Export​

6. Contract Templates Export​

6. Analytics Export​

7. AI Report Export (Comprehensive Analytics Report)​

9. Generic Data Export​

Conversion HTML → Word​

Traductions​

Utilisation​

Backend​

Frontend​

Utilisation avec ExportFormatDialog (pour exports avec date range)​

Utilisation avec EntityExportDialog (pour exports d'entités individuelles)​

Fichiers Modifiés/Créés​

Backend​

Frontend​

Nouvelles Fonctionnalités​

Sélection Personnalisée des Champs​

Exports Planifiés (Scheduled Exports)​

Templates d'Export​

Envoi d'Exports par Email​

État des Migrations vers ExportFormatDialog​

✅ Exports Migrés (utilisent ExportFormatDialog)​

✅ Exports Migrés (utilisent ExportFormatDialog)​

⏳ Exports Non Migrés (peuvent rester avec des boutons directs)​

Prochaines Étapes​

Notes Techniques​

Vue d'ensemble

Sécurité et Performance (2026-01)

Contrôle d'accès

Cleanup automatique

Monitoring

Formats Supportés

PDF

Word (DOCX)

CSV

Excel (XLSX)

JSON

Architecture

Backend

Service Centralisé : `ExportService`

Contrôleur : `ExportController`

Frontend

Composant Réutilisable : `ExportFormatDialog`

Exports Spécifiques

1. Roadmap Export (Sessions)

2. Conversation Export (Agent)

3. Quotes Export

4. Invoices Export

5. Contracts Export

6. Contract Templates Export

6. Analytics Export

7. AI Report Export (Comprehensive Analytics Report)

9. Generic Data Export

Conversion HTML → Word

Traductions

Utilisation

Backend

Frontend

Utilisation avec ExportFormatDialog (pour exports avec date range)

Utilisation avec EntityExportDialog (pour exports d'entités individuelles)

Fichiers Modifiés/Créés

Backend

Frontend

Nouvelles Fonctionnalités

Sélection Personnalisée des Champs

Exports Planifiés (Scheduled Exports)

Templates d'Export

Envoi d'Exports par Email

État des Migrations vers ExportFormatDialog

✅ Exports Migrés (utilisent ExportFormatDialog)

✅ Exports Migrés (utilisent ExportFormatDialog)

⏳ Exports Non Migrés (peuvent rester avec des boutons directs)

Prochaines Étapes

Notes Techniques