Version fonctionnelle

2025-12-12 23:07:26 +01:00
commit cb8b5d9a12
42 changed files with 465285 additions and 0 deletions
--- a/DOCUMENTATION/DOCUMENTATION_36_GUIDE_FRANCAIS.md
+++ b/DOCUMENTATION/DOCUMENTATION_36_GUIDE_FRANCAIS.md
@@ -0,0 +1,642 @@
+# 📋 Endobest Dashboard - Documentation Complète (Français)
+
+**Synthèse complète du système - Guide de référence**
+
+---
+
+## 📌 À Propos du Projet
+
+Le **Dashboard Endobest** est un système automatisé hautement performant de collecte et de traitement de données pour l'étude clinique Endobest. Il récupère les données d'inclusion des patients à partir de plusieurs centres hospitaliers via les APIs Ziwig (RC, GDD, IAM) et génère des rapports JSON et Excel avec validation complète de la qualité.
+
+### Caractéristiques Principales
+
+✅ **Configuration 100% externalisée** - Excel, zéro modification de code
+✅ **Performance optimisée** - 4-5x plus rapide grâce aux appels API optimisés
+✅ **Multithreading avancé** - 20+ workers parallèles
+✅ **Qualité assurée** - Contrôles de cohérence + tests de non-régression
+✅ **Export flexible** - JSON + Excel avec filtrage/tri/transformation
+✅ **Robustesse** - Gestion d'erreurs, token refresh auto, retry automatiques
+
+---
+
+## 🏗️ Structure du Projet
+
+### Modules Python
+
+```
+eb_dashboard.py                    (57.5 KB) - Orchestrateur principal
+└─ Coordonne l'authentification, la collecte, le traitement des données
+
+eb_dashboard_utils.py              (6.4 KB) - Utilitaires
+└─ Clients HTTP thread-safe, navigation JSON, résolution chemins
+
+eb_dashboard_quality_checks.py     (58.5 KB) - Validation de qualité
+└─ Tests de cohérence, non-régression, contrôles de régression
+
+eb_dashboard_excel_export.py       (32 KB) - Export Excel
+└─ Génération de classeurs configurables, filtrage, tri, remplissage
+```
+
+### Configuration & Documentation
+
+```
+config/
+├─ Endobest_Dashboard_Config.xlsx  - Configuration maître (5 feuilles)
+│  ├─ Inclusions_Mapping: Définition des champs
+│  ├─ Organizations_Mapping: Champs d'organisation
+│  ├─ Excel_Workbooks: Métadonnées des classeurs
+│  ├─ Excel_Sheets: Configuration des feuilles
+│  └─ Regression_Check: Règles de validation
+│
+├─ eb_org_center_mapping.xlsx      - Enrichissement organisations (optionnel)
+│
+└─ templates/                      - Modèles Excel
+   ├─ Endobest_Template.xlsx
+   ├─ Statistics_Template.xlsx
+   └─ (Autres modèles)
+
+DOCUMENTATION_10_ARCHITECTURE.md   - Architecture système (43.7 KB)
+DOCUMENTATION_11_FIELD_MAPPING.md  - Extraction et transformation (56.3 KB)
+DOCUMENTATION_12_QUALITY_CHECKS.md - Validation et qualité (60.2 KB)
+DOCUMENTATION_13_EXCEL_EXPORT.md   - Génération Excel (29.6 KB)
+DOCUMENTATION_98_USER_GUIDE.md     - Guide utilisateur (8.4 KB)
+DOCUMENTATION_99_CONFIG_GUIDE.md   - Guide configuration (24.8 KB)
+```
+
+---
+
+## 🚀 Démarrage Rapide
+
+### Installation
+
+```bash
+# 1. Python 3.7+
+python --version
+
+# 2. Dépendances
+pip install httpx openpyxl questionary tqdm rich
+
+# Optionnel (pour recalcul formules Excel)
+pip install pywin32
+pip install pytz
+```
+
+### Exécution Simple
+
+```bash
+# Mode 1: Collecte complète (recommandé)
+python eb_dashboard.py
+# → Collecte + Validation + Export JSON + Excel
+
+# Mode 2: Export Excel rapide (5-15 sec)
+python eb_dashboard.py --excel_only
+# → Utilise données JSON existantes
+
+# Mode 3: Validation uniquement
+python eb_dashboard.py --check-only
+# → Teste les données sans export
+
+# Mode 4: Mode debug
+python eb_dashboard.py --debug
+# → Logs détaillés dans dashboard.log
+```
+
+### Identifiants par Défaut
+
+```
+Login: ziwig-invest2@yopmail.com
+Mot de passe: pbrrA765$bP3beiuyuiyhiuy!agx
+Threads: 12 (ajustable 1-20)
+```
+
+---
+
+## 📊 Flux de Données Principal
+
+### 5 Phases d'Exécution
+
+```
+PHASE 1: INITIALISATION (2-3 sec)
+│
+├─ Authentification IAM
+├─ Échange de token RC
+├─ Chargement configuration
+└─ Setup thread pools
+│
+PHASE 2: ORGANISATIONS & COMPTEURS (5-8 sec)
+│
+├─ GET /api/inclusions/getAllOrganizations
+├─ POST /api/inclusions/inclusion-statistics (20 workers)
+├─ Enrichissement centre optionnel
+└─ Tri organisations
+│
+PHASE 3: COLLECTE INCLUSIONS (2-4 min)
+│
+├─ Boucle Orgs: 20 workers parallèles
+├─ Pour chaque patient:
+│  ├─ Récupération dossier clinique
+│  ├─ Récupération questionnaires (⚡ 1 appel optimisé!)
+│  ├─ Récupération requêtes lab (async)
+│  └─ Traitement champs selon configuration
+└─ Combinaison de toutes les inclusions
+│
+PHASE 4: CONTRÔLE QUALITÉ (10-15 sec)
+│
+├─ Cohérence: API stats vs données réelles
+├─ Non-régression: comparaison avec exécution précédente
+└─ Confirmation utilisateur si problèmes critiques
+│
+PHASE 5: EXPORT (3-20 sec)
+│
+├─ Sauvegarde fichiers JSON
+├─ Génération classeurs Excel
+└─ Logs + temps écoulé
+```
+
+---
+
+## ⚙️ Configuration (Excel)
+
+### Fichier Principal: `Endobest_Dashboard_Config.xlsx`
+
+#### Feuille 1: Inclusions_Mapping
+Définit les champs patients à extraire
+
+| Colonne | Type | Exemple | Usage |
+|---------|------|---------|-------|
+| field_group | Texte | Patient_Identification | Groupe logique |
+| field_name | Texte | Patient_Id | Nom interne |
+| source_type | Texte | q_id / record / inclusion / request / calculated | Où récupérer |
+| source_value | Texte | questionnaire_uuid | Valeur source |
+| field_path | JSON | ["patient_id"] | Chemin JSON |
+| field_condition | Texte | Consent_Signed | Condition d'exécution |
+| value_labels | JSON | {...} | Mappage valeurs |
+| field_template | Texte | $value% | Formatage |
+| true_if_any | JSON | [...] | Conversion booléenne |
+
+#### Feuille 2: Organizations_Mapping
+Champs d'organisation (rarement modifié)
+
+#### Feuille 3: Excel_Workbooks
+Définit les fichiers Excel à créer
+
+| Colonne | Exemple |
+|---------|---------|
+| workbook_name | Endobest_Output |
+| template_path | templates/Endobest_Template.xlsx |
+| output_filename | {workbook_name}_{extract_date_time}.xlsx |
+| output_exists_action | Overwrite / Increment / Backup |
+
+#### Feuille 4: Excel_Sheets
+Configure le contenu et les transformations
+
+| Colonne | Exemple |
+|---------|---------|
+| workbook_name | Endobest_Output |
+| sheet_name | Inclusions |
+| source_type | Inclusions / Organizations / Variable |
+| target | DataTable (named range) |
+| column_mapping | JSON: {"col_id": "patient_id", ...} |
+| filter_condition | JSON: {"status": "active"} |
+| sort_keys | JSON: [{"field": "date", "order": "desc"}] |
+| value_replacement | JSON: [{"type": "bool", ...}] |
+
+#### Feuille 5: Regression_Check
+Règles de validation de qualité
+
+| Colonne | Signification |
+|---------|---|
+| rule_name | Nom de la règle |
+| field_selection | Pipeline include/exclude |
+| bloc_scope | Organisations concernées |
+| transitions | Changements attendus |
+| severity | Warning / Critical |
+
+### Fichier Optionnel: `eb_org_center_mapping.xlsx`
+
+Enrichit organisations avec identifiants centres
+
+```
+Org_Center_Mapping sheet:
+│
+├─ Organization_Name | Center_Name
+├─ Hospital A        | HOSP-A
+├─ Hospital B        | HOSP-B
+└─ ...
+```
+
+---
+
+## 🔄 Cycle de Traitement des Champs
+
+Pour chaque champ configuré:
+
+```
+1. SOURCE
+   ├─ Questionnaire (q_id/q_name/q_category)
+   ├─ Record (dossier clinique)
+   ├─ Inclusion (données inclusion patient)
+   ├─ Request (requête lab)
+   └─ Calculated (fonction personnalisée)
+   │
+2. EXTRACTION
+   ├─ Navigation JSON avec chemin
+   ├─ Support wildcards (*)
+   └─ Valeur brute ou "undefined"
+   │
+3. CONDITION
+   ├─ Si condition = false → "N/A"
+   ├─ Si condition = undefined → "undefined"
+   └─ Sinon → continuer
+   │
+4. TRANSFORMATION
+   ├─ true_if_any (booléen)
+   ├─ value_labels (texte localisé)
+   ├─ field_template (formatage)
+   └─ List joining (aplatissement)
+   │
+5. STOCKAGE
+   └─ output_inclusion[groupe][champ] = valeur_finale
+```
+
+---
+
+## 🛡️ Gestion d'Erreurs
+
+### Stratégie de Récupération
+
+```
+APPEL API
+  │
+  ├─ Succès (200-299)
+  │  └─→ Retour réponse
+  │
+  └─ Erreur
+     ├─ HTTP 401 (Token expiré)
+     │  └─→ Refresh token automatique + Retry
+     ├─ Erreur réseau
+     │  └─→ Retry après 0.5 sec
+     ├─ Autre erreur HTTP
+     │  └─→ Retry après 0.5 sec
+     │
+     └─ Max 10 tentatives (ERROR_MAX_RETRY)
+        └─ Si écec: Erreur critique → Exit
+```
+
+### Dégradation Gracieuse
+
+- **Fichier org mapping manquant?** → Ignoré silencieusement
+- **Template Excel manquant?** → Erreur claire avec chemin
+- **Problèmes qualité critiques?** → Confirmation utilisateur
+- **Erreur thread?** → Shutdown gracieux, conservation données partielles
+
+---
+
+## 📈 Performance & Optimisations
+
+### Impact Optimisation API Questionnaires
+
+```
+AVANT (Lent):
+└─ 1,200 patients × 15 questionnaires
+   = 18,000 appels API
+   = 15-30 minutes
+
+APRÈS (Optimisé):
+└─ 1,200 patients × 1 appel
+   = 1,200 appels API
+   = 2-5 minutes
+   = GAIN: 3-6x plus rapide ⚡
+```
+
+### Temps Typiques
+
+| Étape | Durée |
+|-------|-------|
+| Login + Config | 2-3 sec |
+| Compteurs (20 workers) | 5-8 sec |
+| Inclusions (avec APIs) | 2-4 min |
+| Checks qualité | 10-15 sec |
+| Export JSON | 3-5 sec |
+| Export Excel | 5-15 sec |
+| **TOTAL** | **2.5-5 min** |
+
+---
+
+## ✅ Contrôles de Qualité
+
+### 1. Test de Cohérence
+Vérifie que les compteurs API correspondent aux données réelles
+
+```
+Pour chaque organisation:
+  API Count = statistiques fournies
+  Actual Count = enregistrements collectés
+
+  Δ ≤ 10%  → ⚠️  Avertissement
+  Δ > 10%  → 🔴 Critique
+```
+
+### 2. Test de Non-Régression
+Détecte changements inattendus vs exécution précédente
+
+```
+Règles configurables:
+├─ Sélection champs (pipeline include/exclude)
+├─ Patterns de transition (états attendus)
+├─ Exceptions (organisations spécifiques)
+└─ Sévérité (Warning/Critical)
+
+Détections:
+├─ Nouvelles inclusions
+├─ Inclusions supprimées
+├─ Changements champs
+└─ Transitions d'état invalides
+```
+
+---
+
+## 📁 Fichiers de Sortie
+
+### JSON Files
+
+**endobest_inclusions.json** (~6-7 MB)
+```json
+[
+  {
+    "Patient_Identification": {
+      "Organisation_Id": "...",
+      "Organisation_Name": "...",
+      "Center_Name": "...",
+      "Patient_Id": "...",
+      "Pseudo": "...",
+      "Patient_Name": "...",
+      "Patient_Birthday": "...",
+      "Patient_Age": ...
+    },
+    "Inclusion": { ... },
+    "Extended_Fields": { ... },
+    "Endotest": { ... }
+  }
+]
+```
+
+**endobest_organizations.json** (~17-20 KB)
+```json
+[
+  {
+    "id": "org-uuid",
+    "name": "Hospital A",
+    "Center_Name": "HOSP-A",
+    "patients_count": 45,
+    "preincluded_count": 8,
+    "included_count": 35,
+    "prematurely_terminated_count": 2
+  }
+]
+```
+
+### Excel Files
+Générés selon configuration, avec:
+- Filtrage (conditions AND)
+- Tri (multi-clés avec datetime)
+- Remplacement valeurs (strict type matching)
+- Remplissage cellules/plages nommées
+- Recalcul formules (optionnel via win32com)
+
+### Log File
+**dashboard.log**
+- Événements par exécution
+- Avertissements API
+- Erreurs avec contexte
+- Statistiques exécution
+
+---
+
+## 🎯 Fonctions Personnalisées
+
+### Fonctions Disponibles (Block 6)
+
+#### 1. search_in_fields_using_regex
+Recherche pattern dans plusieurs champs
+
+```json
+{
+  "source_id": "search_in_fields_using_regex",
+  "field_path": [".*surgery.*", "Indication", "Previous_Surgery"]
+}
+```
+
+#### 2. extract_parentheses_content
+Extrait texte entre parenthèses
+
+```json
+{
+  "source_id": "extract_parentheses_content",
+  "field_path": ["Status_Field"]
+}
+```
+
+#### 3. append_terminated_suffix
+Ajoute suffixe si prématurément terminé
+
+```json
+{
+  "source_id": "append_terminated_suffix",
+  "field_path": ["Inclusion_Status", "IsPrematurelyTerminated"]
+}
+```
+
+#### 4. if_then_else
+Logique conditionnelle unifiée
+
+```json
+{
+  "source_id": "if_then_else",
+  "field_path": ["is_defined", "Patient_Id", "$\"DEFINED\"", "$\"UNDEFINED\""]
+}
+```
+
+**Opérateurs:** `is_true`, `is_false`, `is_defined`, `is_undefined`, `all_true`, `all_defined`, `==`, `!=`
+
+---
+
+## 🔑 APIs Utilisées
+
+### Authentification (IAM)
+
+```
+POST https://api-auth.ziwig-connect.com/api/auth/ziwig-pro/login
+Request: {username, password}
+Response: {access_token, userId}
+
+POST https://api-hcp.ziwig-connect.com/api/auth/config-token
+Headers: Authorization: Bearer {master_token}
+Response: {access_token, refresh_token}
+```
+
+### Research Clinic (RC)
+
+```
+GET /api/inclusions/getAllOrganizations
+POST /api/inclusions/inclusion-statistics
+POST /api/inclusions/search?limit=1000&page=1
+POST /api/records/byPatient
+POST /api/surveys/filter/with-answers ⚡ OPTIMISÉE
+```
+
+### Lab (GDD)
+
+```
+GET /api/requests/by-tube-id/{tubeId}
+```
+
+---
+
+## 📚 Documentation Détaillée
+
+| Document | Contenu |
+|----------|---------|
+| **DOCUMENTATION_10_ARCHITECTURE.md** | Design système, APIs, multithreading |
+| **DOCUMENTATION_11_FIELD_MAPPING.md** | Extraction champs, fonctions, exemples |
+| **DOCUMENTATION_12_QUALITY_CHECKS.md** | Framework QA, règles régression |
+| **DOCUMENTATION_13_EXCEL_EXPORT.md** | Génération Excel, pipeline transformation |
+| **DOCUMENTATION_98_USER_GUIDE.md** | Instructions utilisateur, FAQ |
+| **DOCUMENTATION_99_CONFIG_GUIDE.md** | Référence configuration, tableaux Excel |
+
+---
+
+## 🆘 Dépannage Courant
+
+| Problème | Cause | Solution |
+|----------|-------|----------|
+| **Login échoue** | Credentials invalides | Vérifier identifiants |
+| **Template non trouvé** | Chemin incorrect | Vérifier `config/templates/` |
+| **Pas de données Excel** | Filtre trop restrictif | Vérifier filter_condition |
+| **Script lent** | Trop peu de threads | Augmenter jusqu'à 20 |
+| **Erreur configuration** | JSON invalide | Valider JSON dans Excel |
+
+---
+
+## 🎯 Cas d'Usage Typiques
+
+### 1. Collecte Hebdomadaire
+```bash
+# Programmé chaque lundi 6h
+python eb_dashboard.py
+```
+
+### 2. Reconfiguration Rapide
+```bash
+# Modification fichier Excel config
+python eb_dashboard.py --excel_only
+# Résultats en 5-15 secondes
+```
+
+### 3. Vérification Qualité
+```bash
+python eb_dashboard.py --check-only
+# Validation avant distribution
+```
+
+### 4. Débogage
+```bash
+python eb_dashboard.py --debug
+# Consulter dashboard.log
+```
+
+---
+
+## 🔐 Sécurité
+
+⚠️ **Points Importants:**
+- Fichiers JSON contiennent données patients
+- Stocker en lieu sûr
+- Gérer selon protocoles établis
+- Supprimer fichiers `_old` si inutiles
+- Logs peuvent contenir infos sensibles
+
+---
+
+## 💡 Bonnes Pratiques
+
+1. **Première exécution:** Toujours mode complet (collecte)
+2. **Configurations:** Tester avec `--excel_only`
+3. **Programmation:** Utiliser task scheduler ou cron
+4. **Threads:** Plus = plus rapide (mais utilisation réseau)
+5. **Sauvegardes:** Les fichiers `_old` sont automatiques
+
+---
+
+## 📞 Support
+
+### Vérifications
+1. Consulter ce document
+2. Consulter FAQ (DOCUMENTATION_98_USER_GUIDE.md)
+3. Consulter dashboard.log
+4. Exécuter avec `--debug`
+
+### Logs
+```bash
+# Dernières 50 lignes
+tail -n 50 dashboard.log
+
+# Erreurs uniquement
+grep ERROR dashboard.log
+
+# Exécution spécifique
+grep "2025-01-15" dashboard.log
+```
+
+---
+
+## ✨ Points Forts
+
+✅ Configuration 100% Excel (zéro code)
+✅ Performance 4-5x supérieure
+✅ Gestion erreurs robuste
+✅ Interface utilisateur conviviale
+✅ Architecture maintenable
+✅ Documentation complète
+✅ Prêt production
+
+---
+
+## 📝 Résumé Technique
+
+- **Langage:** Python 3.7+
+- **Modules:** httpx, openpyxl, questionary, tqdm, rich
+- **Architecture:** Multi-threading, async I/O
+- **Configuration:** 100% Excel (5 feuilles)
+- **Export:** JSON + Excel
+- **Validation:** Cohérence + non-régression
+- **Performance:** 2.5-5 minutes (1,200+ patients)
+- **Logging:** dashboard.log complet
+
+---
+
+## 🎓 Prochaines Étapes
+
+**Démarrage:**
+1. Installer Python 3.7+
+2. `pip install httpx openpyxl questionary tqdm rich`
+3. `python eb_dashboard.py`
+
+**Configuration:**
+1. Consulter DOCUMENTATION_99_CONFIG_GUIDE.md
+2. Éditer config/Endobest_Dashboard_Config.xlsx
+3. Ajouter/modifier champs selon besoin
+
+**Avancé:**
+1. DOCUMENTATION_11_FIELD_MAPPING.md (extraction)
+2. DOCUMENTATION_12_QUALITY_CHECKS.md (validation)
+3. DOCUMENTATION_13_EXCEL_EXPORT.md (export)
+
+---
+
+**Version:** 1.0
+**Date:** 2025-11-08
+**Statut:** ✅ Production Ready
+**Langue:** Français (avec documentation anglaise complète)
+
+**Pour plus de détails, consultez les fichiers DOCUMENTATION_*.md**