Stack Python - Plan d'Évolution

Date : 2026-01-26
Statut : ✅ Migration 100% complète | Plus de fallback Node.js
Dernière mise à jour : 2026-01-26

🎯 Architecture 100% Python

La génération de documents est désormais entièrement gérée par les services Python. Les fallbacks Node.js ont été supprimés.

Changements Majeurs (2026-01-26)

pdfkit, docx, xlsx-style : Dépendances npm supprimées
USE_PYTHON_PDF : Variable d'environnement supprimée (Python toujours actif)
EXPORTS_V2 → EXPORTS : Queue simplifiée
Code mort supprimé : GmailService, db.query(), markTokenAsUsed()

Services Python

PDF Generation : WeasyPrint pour qualité CSS3
Word Generation : python-docx pour formatage avancé
Excel Generation : openpyxl pour formatage avancé
OCR : Vision APIs (GPT-4o) + Tesseract.js fallback
Embeddings : sentence-transformers (local)
Intent Detection : transformers (local)

📊 Architecture Actuelle

flowchart TB
    subgraph frontend [Frontend React]
        UI[User Interface]
    end

    subgraph backend [NestJS Backend]
        API[API Controllers]
        Workers[BullMQ Workers]
        VisionOCR[Vision OCR Service]
        Tesseract[Tesseract.js Fallback]
    end

    subgraph python [Python Services]
        Embeddings[Embeddings Service]
        Qdrant[Qdrant Service]
        PDF[PDF Generation - WeasyPrint]
        Word[Word Generation - python-docx]
        Excel[Excel Generation - openpyxl]
        Intent[Intent Detection - Transformers]
    end

    subgraph external [APIs Externes]
        GPT4V[GPT-4o Vision - Clé utilisateur]
        OpenAI[OpenAI LLM]
    end

    subgraph storage [Storage]
        PostgreSQL[(PostgreSQL)]
        Redis[(Redis)]
        QdrantDB[(Qdrant Vector DB)]
    end

    UI --> API
    API --> VisionOCR
    VisionOCR --> GPT4V
    VisionOCR -.-> Tesseract

    API --> python
    Workers --> python
    python --> QdrantDB
    API --> OpenAI

✅ Phases Complétées

Phase 1 : OCR via Vision APIs ✅

Remplacé EasyOCR (bugs preds_str) par Vision APIs + Tesseract fallback.

Stratégie	Description
Vision API	GPT-4o via clé utilisateur - Haute qualité
Tesseract.js	Fallback local - Toujours disponible

Phase 2 : PDF Generation en Python ✅

Migré vers WeasyPrint pour meilleur rendu CSS3.

Service	Backend
Factures	`POST /api/pdf/invoice`
Devis	`POST /api/pdf/quote`
Contrats	`POST /api/pdf/html-to-pdf`
Exports tables	`POST /api/pdf/table-export` (paysage)

Phase 3 : Intent Detection en Python ✅

Classification locale avec facebook/bart-large-mnli.

Endpoint	Description
`POST /api/intent/classify`	Classifier une requête
`POST /api/intent/filters`	Extraire filtres de recherche

Phase 4 : OpenRouter ❌ Annulé

Décision de garder simple : clé OpenAI utilisateur + Tesseract fallback.

Phase 5 : Word & Excel Generation ✅

Migré vers python-docx et openpyxl pour meilleur formatage.

Format	Endpoint	Librairie
Word (table)	`POST /api/word/table-export`	python-docx
Word (conversation)	`POST /api/word/conversation`	python-docx
Excel (single)	`POST /api/excel/single-sheet`	openpyxl
Excel (multi)	`POST /api/excel/multi-sheet`	openpyxl
Excel (conversation)	`POST /api/excel/conversation`	openpyxl

📋 État des Services

Génération de Documents

Format	Service NestJS	Service Python	Status
PDF - Factures	`QuotesInvoicesPdfService`	`POST /api/pdf/invoice`	✅ Python uniquement
PDF - Devis	`QuotesInvoicesPdfService`	`POST /api/pdf/quote`	✅ Python uniquement
PDF - Contrats	`ContractsPdfService`	`POST /api/pdf/html-to-pdf`	✅ Python uniquement
PDF - Tables	`ExportPdfService`	`POST /api/pdf/table-export`	✅ Python uniquement
Word - Tables	`ExportWordService`	`POST /api/word/table-export`	✅ Python uniquement
Excel - Simple	`ExportExcelSingleService`	`POST /api/excel/single-sheet`	✅ Python uniquement
Excel - Multiple	`ExportExcelMultipleService`	`POST /api/excel/multi-sheet`	✅ Python uniquement
Excel - Bookings	`BookingsController`	`POST /api/excel/single-sheet`	✅ Python uniquement
CSV	`ExportCsvService`	-	⏸️ Node.js (simple)

🏷️ Renommage Effectué

Le service a été renommé de python-ml-service à python-services pour refléter ses capacités étendues.

Aspect	Ancien	Nouveau
Nom du service	`python-ml-service`	`python-services`
Docker Compose	`python-ml-service`	`python-services`
URL interne	`http://python-ml-service:8000`	`http://python-services:8000`
Variable env	`PYTHON_ML_SERVICE_URL`	`PYTHON_ML_SERVICE_URL` (rétrocompatible)
Image CI/CD	`python-ml-service:*`	`python-services:*`

💰 Économies et Bénéfices

Aspect	Avant	Après	Bénéfice
OCR	EasyOCR (bugs)	GPT-4o + Tesseract	Fiabilité
PDF	pdfkit (CSS limité)	WeasyPrint (CSS3)	Qualité
Word	docx (Node.js)	python-docx	Formatage
Excel	xlsx-style (Node.js)	openpyxl	Formatage
Intent	OpenAI API	Modèles locaux	~$50-100/mois

🔑 Configuration

# .env
PYTHON_SERVICE_URL=http://python-services:8000

# OCR - Vision API avec Tesseract.js fallback
USE_VISION_OCR=true

# Note: Les variables USE_PYTHON_* ont été supprimées
# Les services PDF, Word, Excel et Intent utilisent toujours Python

🚀 Déploiement

Reconstruire les services

# Développement
docker-compose -f infra/docker-compose.dev.yml up -d --build python-services api worker

# Production
docker-compose -f infra/docker-compose.prod.yml up -d --build python-services api worker

Vérifier les services

# Health check Python
curl http://localhost:8000/health

# Liste des fonctionnalités
curl http://localhost:8000/

# Health Word
curl http://localhost:8000/api/word/health

# Health Excel
curl http://localhost:8000/api/excel/health

📋 Prochaines Étapes

Phase 6 : Vérification & Stabilisation ✅

Priorité : Haute | Effort : Faible

Tests de connectivité et validation de la migration :

Tâche	Description	Status
Tests Docker	Connectivité backend ↔ Python en Docker	✅ Validé
Logs & Monitoring	Logs clairs et exploitables	✅ Validé
Variables d'env	Simplifiées (suppression USE_PYTHON_*)	✅ Validé
Tests E2E	Tester chaque endpoint avec des données réelles	⏳ À faire

Phase 7 : Nettoyage du Code Legacy ✅

Priorité : Moyenne | Effort : Moyen

Suppression des anciennes implémentations Node.js :

Tâche	Description	Status
Supprimer fallback PDF	Retirer `quotes-invoices-pdf-direct.service.ts`, `contracts-pdf-direct.service.ts`	✅ Fait
Supprimer fallback Excel	Retirer `export-excel-helpers.service.ts` (xlsx-style)	✅ Fait
Simplifier services	Retirer la logique conditionnelle `usePythonPdf/Word/Excel`	✅ Fait
Variables d'environnement	Retirer `USE_PYTHON_PDF`, `USE_PYTHON_WORD`, `USE_PYTHON_EXCEL`, `USE_PYTHON_INTENT`	✅ Fait

Note: Les dépendances npm pdfkit, docx et xlsx-style sont conservées pour d'autres fonctionnalités (session roadmap Word, extraction DOCX, agent Excel export).

Phase 8 : Améliorations Avancées ⏳

Priorité : Moyenne | Effort : Moyen

Optimisations pour la performance et la maintenabilité :

Tâche	Description	Status
Cache Redis	Ajouter du caching côté Python pour documents récurrents	⏳ À faire
Métriques Prometheus	Exposer des métriques pour monitoring	⏳ À faire
Rate Limiting	Limiter les requêtes pour éviter surcharge	⏳ À faire
Health Checks avancés	Vérifier dépendances (Qdrant, Redis) dans health	⏳ À faire
Templates personnalisables	Permettre templates PDF/Word custom par tenant	⏳ À faire

Phase 9 : Nouvelles Fonctionnalités ⏳

Priorité : Basse | Effort : Élevé

Fonctionnalités additionnelles possibles :

Tâche	Description	Status
Rapports analytiques	Génération de rapports avec graphiques	⏳ À planifier
Conversion DOCX → PDF	Convertir documents Word en PDF	⏳ À planifier
Compression fichiers	Optimiser la taille des exports	⏳ À planifier
Watermarks	Ajouter filigranes aux PDF	⏳ À planifier
Signatures numériques	Support des signatures électroniques	⏳ À planifier
Merge PDF	Fusionner plusieurs PDF en un	⏳ À planifier

🚀 CI/CD Optimisé

Pipeline GitLab CI

Le pipeline a été optimisé avec des builds parallèles :

Stage 1: lint
Stage 2: test
Stage 3: build:api | build:web | build:python-services | build:liquibase (parallèle)
Stage 4: deploy:prod (uniquement sur main)

Optimisations appliquées

Optimisation	Impact
Jobs parallèles	4 builds simultanés → temps réduit ~50%
Cache npm	Réutilisation `node_modules/` entre jobs
Docker BuildKit	Meilleur cache des layers Docker
PyTorch CPU-only	Image Python ~5x plus petite (~2GB vs ~10GB)
Suppression EasyOCR	Non utilisé depuis migration Vision OCR

Image Python optimisée

# PyTorch CPU-only (200MB vs 6GB avec CUDA)
RUN pip install torch --index-url https://download.pytorch.org/whl/cpu

# Dépendances essentielles uniquement
# - sentence-transformers (embeddings)
# - weasyprint (PDF)
# - python-docx (Word)
# - openpyxl (Excel)
# - qdrant-client (vector DB)

🔗 Documentation Associée

PYTHON_STACK_IMPLEMENTATION.md - Implémentation détaillée
AGENTS_ERROR_MESSAGES.md - Messages d'erreur

🎯 Architecture 100% Python​

Changements Majeurs (2026-01-26)​

Services Python​

📊 Architecture Actuelle​

✅ Phases Complétées​

Phase 1 : OCR via Vision APIs ✅​

Phase 2 : PDF Generation en Python ✅​

Phase 3 : Intent Detection en Python ✅​

Phase 4 : OpenRouter ❌ Annulé​

Phase 5 : Word & Excel Generation ✅​

📋 État des Services​

Génération de Documents​

🏷️ Renommage Effectué​

💰 Économies et Bénéfices​

🔑 Configuration​

🚀 Déploiement​

Reconstruire les services​

Vérifier les services​

📋 Prochaines Étapes​

Phase 6 : Vérification & Stabilisation ✅​

Phase 7 : Nettoyage du Code Legacy ✅​

Phase 8 : Améliorations Avancées ⏳​

Phase 9 : Nouvelles Fonctionnalités ⏳​

🚀 CI/CD Optimisé​

Pipeline GitLab CI​

Optimisations appliquées​

Image Python optimisée​

🔗 Documentation Associée​