abdelkouddous/EB_Dashboard

Fork 0

Files

Abdelkouddous LHACHIMI cb8b5d9a12 Version fonctionnelle

2025-12-12 23:07:26 +01:00

16 KiB

Raw Blame History

📋 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

# 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

# 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)

[
  {
    "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)

[
  {
    "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

{
  "source_id": "search_in_fields_using_regex",
  "field_path": [".*surgery.*", "Indication", "Previous_Surgery"]
}

2. extract_parentheses_content

Extrait texte entre parenthèses

{
  "source_id": "extract_parentheses_content",
  "field_path": ["Status_Field"]
}

3. append_terminated_suffix

Ajoute suffixe si prématurément terminé

{
  "source_id": "append_terminated_suffix",
  "field_path": ["Inclusion_Status", "IsPrematurelyTerminated"]
}

4. if_then_else

Logique conditionnelle unifiée

{
  "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

# Programmé chaque lundi 6h
python eb_dashboard.py

2. Reconfiguration Rapide

# Modification fichier Excel config
python eb_dashboard.py --excel_only
# Résultats en 5-15 secondes

3. Vérification Qualité

python eb_dashboard.py --check-only
# Validation avant distribution

4. Débogage

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

Première exécution: Toujours mode complet (collecte)
Configurations: Tester avec --excel_only
Programmation: Utiliser task scheduler ou cron
Threads: Plus = plus rapide (mais utilisation réseau)
Sauvegardes: Les fichiers _old sont automatiques

📞 Support

Vérifications

Consulter ce document
Consulter FAQ (DOCUMENTATION_98_USER_GUIDE.md)
Consulter dashboard.log
Exécuter avec --debug

Logs

# 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:

Installer Python 3.7+
pip install httpx openpyxl questionary tqdm rich
python eb_dashboard.py

Configuration:

Consulter DOCUMENTATION_99_CONFIG_GUIDE.md
Éditer config/Endobest_Dashboard_Config.xlsx
Ajouter/modifier champs selon besoin

Avancé:

DOCUMENTATION_11_FIELD_MAPPING.md (extraction)
DOCUMENTATION_12_QUALITY_CHECKS.md (validation)
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

16 KiB Raw Blame History Unescape Escape