documentations/kpi_health_check_plan.md

KPI Health Check (Panel) — Plan global

1) Contexte & objectif

En NPO, on reçoit des plaintes client (site(s) impacté(s)). L’objectif est de pouvoir, en quelques minutes, vérifier si les KPI radio sont:

• Dégradés récemment
• Dégradés depuis longtemps (persistants)
• En voie de résolution / résolus

Le but est d’avoir une application Panel simple à utiliser, mais “expert-friendly”, qui standardise l’analyse et produit un rapport exportable.

2) Entrées & formats de données

2.1 Fichiers

• Rapports KPI par technologie: 2G / 3G / LTE
• Format: .csv ou .zip contenant un (ou plusieurs) .csv
• Séparateur: ; (latin1) comme dans les apps existantes

2.2 Colonnes clés attendues

• Date: PERIOD_START_TIME (parfois date seule ou date+heure)
• Identifiant NE/site/cell (variable selon RAT)
  • 2G: BCF name / DN
  • 3G: WBTS name / DN
  • LTE: LNBTS name / DN

2.3 KPI (liste fournie)

• Les colonnes KPI sont nombreuses et hétérogènes.
• Il faut distinguer:
  • KPI “taux” (availability, success rate, CSSR, etc.) => agrégation moyenne
  • KPI “compteurs/volumes/traffic” => agrégation somme

3) Sorties attendues

3.1 Résultats UI

• Tableau “Health Summary” par site:
  • Nombre de KPI dégradés (par RAT)
  • Nombre de KPI persistants
  • Top KPI les plus critiques
• Drill-down par site:
  • Courbes temporelles
  • Jours dégradés
  • Comparaison baseline vs récent

3.2 Export

• Export Excel d’un rapport complet:
  • Résumé datasets
  • Règles KPI (seuils/direction)
  • Résumé site
  • Détails par KPI/site
  • Série journalière (optionnel / selon volume)

4) Modèle de détection (logique “expert”)

4.1 Normalisation

• Parsing date en datetime
• Construction date_only
• Extraction d’un site_code (ou code site) depuis le nom (pattern numérique / split comme dans l’app trafic)
• Enrichissement via physical_db (City, Latitude/Longitude) comme dans trafic_analysis_panel.py

4.2 Règles KPI (paramétrables)

Chaque KPI doit avoir:

• direction:
  • higher_is_better (availability, success rate, CSSR, throughput, traffic)
  • lower_is_better (drop rate, blocking, congestion, loss, discard, RTWP, PRB usage)
• sla (optionnel): seuil absolu
• agg: mean ou sum

4.3 Fenêtres temporelles

Paramètres globaux:

• Baseline window (ex: 30 jours)
• Recent window (ex: 7 jours)
• Min consecutive bad days (ex: 3 jours) => persistant

4.4 Critères de dégradation

Pour un couple (site, KPI, RAT):

• Dégradation relative vs baseline
  • ex: variation > X% dans le “mauvais sens”
• Dégradation absolue vs SLA
  • ex: availability < 98% ou drop > 2%

4.5 Classification (états)

• OK: pas de dégradation
• DEGRADED: dégradé récemment
• PERSISTENT_DEGRADED: dégradé récemment + streak >= N jours
• RESOLVED (V2): dégradé avant mais OK sur les derniers jours
• NO_DATA: pas de points exploitables

5) UX / écrans (Panel)

5.0 Mode multipage (Portal)

L’app cible est un portal Panel multipage qui regroupe plusieurs pages (apps) sur un seul serveur Panel.

Pages initiales:

• Global Traffic Analysis (page existante: panel_app/trafic_analysis_panel.py)
• KPI Health Check (nouvelle page: panel_app/kpi_health_check_panel.py)

Navigation:

• menu latéral (sélecteur de page)
• la sidebar et le contenu principal changent selon la page sélectionnée

5.1 Sidebar (configuration)

• Upload 2G/3G/LTE
• Période d’analyse optionnelle
• Paramètres: baseline/recent/threshold/persistance
• Boutons:
  • Charger & construire les règles
  • Lancer le health check
  • Export Excel

5.2 Main

• Datasets summary
• KPI Rules table (editable)
• Site Summary table
• Drill-down:
  • Sélection site
  • Sélection RAT
  • Sélection KPI
  • Courbe KPI
  • Table KPI/site (statuts)

6) Architecture code & organisation

6.1 Modules

Objectif: app modulaire, pas un fichier monolithique.

• panel_app/kpi_health_check_panel.py
  • UI Panel (widgets, layout)
  • branchement des callbacks
  • aucune logique “métier” lourde
• panel_app/panel_portal.py
  • page d’accueil + navigation multipage
  • import des pages et affichage via get_page_components()
• process_kpi/kpi_health_check/io.py
  • lecture ZIP/CSV
  • support ZIP multi-CSV (V2)
• process_kpi/kpi_health_check/normalization.py
  • détection colonne date / parsing
  • extraction site_code depuis BCF/WBTS/LNBTS/DN
  • agrégation journalière (mean vs sum)
  • enrichissement physical_db (City/Lat/Lon)
• process_kpi/kpi_health_check/rules.py
  • génération des règles KPI (direction, SLA, agg)
  • validation / normalisation des règles
• process_kpi/kpi_health_check/engine.py
  • calcul baseline vs récent
  • classification (OK / DEGRADED / PERSISTENT_DEGRADED / RESOLVED)
  • construction tables output
• process_kpi/kpi_health_check/multi_rat.py
  • synthèse cross-RAT par site
  • “top anomalies” multi-RAT
• process_kpi/kpi_health_check/export.py
  • build Excel bytes (réutilise panel_app/convert_to_excel_panel.py)

6.2 Fonctions clés

• Lecture ZIP/CSV
• Détection colonnes date & ID
• Construction dataset journalier
• Génération règles KPI
• Évaluation health check
• Export Excel

6.3 Règle site_code + enrichissement physical DB (comme l’app trafic)

• Extraction code site
  • stratégie principale: logique proche de trafic_analysis_panel.py (split / préfixe numérique du nom)
  • fallback: regex sur séquence de chiffres dans le nom
• Enrichissement
  • charger physical_db/physical_database.csv via get_physical_db()
  • construire code depuis Code_Sector (split('_')[0]) puis cast int
  • jointure sur le code pour récupérer City, Longitude, Latitude

7) Roadmap / itérations

V1 (MVP)

• [DONE] Upload 2G/3G/LTE (multi-RAT)
• [DONE] Détection KPI numériques
• [DONE] Règles KPI éditables
• [DONE] Détection DEGRADED / PERSISTENT_DEGRADED / OK
• [DONE] Drill-down simple + export

V2 (expert)

• [DONE] RESOLVED (dégradé puis OK)
• [DONE] Support ZIP multi-CSV
• [N/A] Support “cell-level” vs “site-level” (switch) (KPI confirmés par site)
• [DONE] Score de criticité (pondération trafic OK avec conversion 2G MB -> GB; pas de données population/criticité client)
• [DONE] Table “Top anomalies” multi-RAT (cross-RAT)
• [DONE] Visualisations avancées (heatmap par jour, histogrammes, etc.)

V3 (industrialisation)

• [DONE] Presets de règles (JSON local) + sauvegarde/chargement dans l'UI
• [TODO] Gestion profils / sauvegarde de configuration
• [TODO] Import automatique de “liste des sites plaintes”
• [N/A] Génération PDF (optionnel) et pack de preuves

8) Points ouverts à confirmer

• [DONE] Les KPI sont par site
• [DONE] Les ZIP contiennent-ils parfois plusieurs CSV ? (support multi-CSV implémenté)
• [PARTIAL] Format exact de PERIOD_START_TIME sur tous les rapports ? (parsing renforcé, à valider sur tes fichiers)
• [TODO] Extraction du code site: règle unique ou dépend du naming ?

9) Critères de réussite

• Charger un rapport KPI et obtenir un top sites dégradés en < 1 minute
• Pouvoir isoler rapidement: depuis quand, sur quels KPI, et si c’est persistant
• Export Excel exploitable pour partage interne