EB_Dashboard/DOCUMENTATION/DOCUMENTATION_36_GUIDE_FRANCAIS.md

# 📋 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**