documentations/kpi_health_check_improvement_roadmap.md

KPI Health Check (Panel) — Plan d’amélioration (Roadmap)

0) Objectif

Consolider l’app KPI Health Check pour une utilisation “NPO / exploitation” plus fluide et plus actionnable.

Axes demandés:

• [A] Exploitation / priorisation (alert pack, ops queue, snapshot/delta, RCA hints)
• [B] Visualisation (map des sites, corrélation KPI)

Décision prise:

• “Complaint sites only” = UI + export Excel (les deux)

Non-scope:

• Génération PDF / evidence pack (optionnel, non prioritaire).

0.1) Principes (invariants)

• Compatibilité: ne pas casser l’existant (tables, drill-down, export principal).
• Performance: éviter les recalculs inutiles (réutiliser caches/versions déjà en place dans l’UI).
• Robustesse données: gérer proprement NO_DATA, colonnes manquantes, coordonnées absentes.
• Export Excel: garder des noms d’onglets stables (important pour les utilisateurs qui automatisent).

---

1) État actuel (déjà en place)

1.1 Flux de l’app

• Upload KPI 2G/3G/LTE (CSV/ZIP)
• Normalisation date_only, site_code, enrichissement éventuel City/Lat/Lon
• Construction + édition des rules (direction, sla)
• Health-check: OK / DEGRADED / PERSISTENT_DEGRADED / RESOLVED / NO_DATA
• Synthèses:
  • Site_Summary
  • MultiRAT_Summary (score criticité)
  • Top_Anomalies (score anomaly)
• Drill-down: trend + heatmap + histogram
• Export Excel (Datasets / KPI Rules / Summary / Status / MultiRAT / Top)
• Gestion: presets + profiles
• Filtre existant: checkbox Only complaint sites (filtre les tables multi-rat / top anomalies)

1.2 Fichiers “source of truth”

• UI:
  • panel_app/kpi_health_check_panel.py
• Export:
  • process_kpi/kpi_health_check/export.py
• Calculs:
  • process_kpi/kpi_health_check/engine.py
  • process_kpi/kpi_health_check/multi_rat.py

---

2) Roadmap (ordre recommandé)

Phase 1 — Complaint sites only (UI + Export) (priorité haute)

2.1 UI: onglet dédié “Complaint sites only”

But: ne plus dépendre d’un filtre à cocher; fournir un écran prêt à l’emploi.

Contenu onglet:

• MultiRAT Summary (Complaint)
• Top Anomalies (Complaint)
• Optionnel: un petit “mini résumé” (counts)

Spécifications:

• Les tables doivent être toujours filtrées sur is_complaint_site == True.
• Les interactions existantes restent:
  • double-click (ou click) pour appliquer le drill-down (_handle_double_click + _apply_drilldown_selection).

Implémentation (point d’intégration):

• Créer 2 nouveaux Tabulator dans kpi_health_check_panel.py, alimentés par une fonction de refresh dédiée.
• Réutiliser la logique existante de flag is_complaint_site déjà posée dans _apply_complaint_flags().

Critères d’acceptation:

• Après Run health check, l’onglet affiche uniquement les complaint sites.
• Les filtres “city / min score / top RAT / status” ne doivent pas casser l’onglet.
• Si la liste plaintes est vide/non trouvée, l’onglet reste vide (ou affiche un message) sans erreur.

2.2 Export Excel: feuilles “Complaint sites only”

But: avoir un export directement partageable “ops / plaintes”.

Feuilles proposées:

• Complaint_MultiRAT
• Complaint_Top_Anomalies

Option bonus (si utile):

• Complaint_Ops_Queue (par site) = tri par criticité pondérée trafic si dispo.

Implémentation (point d’intégration):

• Étendre process_kpi/kpi_health_check/export.py:
  • soit en ajoutant de nouveaux paramètres optionnels,
  • soit en ajoutant des dfs supplémentaires en fin de liste (compatibilité).
• Dans kpi_health_check_panel.py, construire les df “complaint only” à partir de current_multirat_df / current_top_anomalies_df ou des raw (selon besoin) et les fournir à l’export.

Critères d’acceptation:

• L’export contient les 2 feuilles complaint.
• Les feuilles complaint restent vides si aucune liste plaintes n’est chargée et aucun fichier data/complaint_sites.* n’est trouvé.
• Les noms d’onglets restent < 31 caractères et sans caractères invalides (contrainte Excel).

---

Phase 2 — Ops Queue + Alert Pack (priorité haute)

2.3 “Ops Queue” (table unique priorisée)

But: une table de travail qui regroupe le besoin exploitation:

• 1 ligne par site
• priorité = criticité (pondérée trafic si dispo)
• infos clés: impacted_rats, persistent_kpis_total, degraded_kpis_total, resolved_kpis_total, is_complaint_site, trafic

Implémentation:

• Construire ops_queue_df à partir de current_multirat_raw (qui contient déjà scores + flags).
• Ajouter un onglet UI “Ops Queue” + une feuille Excel.

2.4 “Alert Pack” export court

But: un export “prêt à envoyer” (résumé + ops queue + top anomalies) sans l’exhaustivité.

• Nouveau bouton export, ou une option dans l’export existant.

---

Phase 3 — Snapshot + Delta (priorité haute)

2.5 Snapshot de run

But: figer un run (résultats + paramètres + rules) pour audit et comparaison.

Format recommandé:

• json (simple) ou parquet (plus robuste pour gros volumes). Pour MVP: JSON.

Contenu snapshot (proposition):

• snapshot_version: int
• created_at: ISO datetime
• profile_config: dict (baseline/recent/thr/min streak + filtres)
• rules_df: list[dict] (records)
• multirat_df: list[dict]
• top_anomalies_df: list[dict]

UI:

• FileDownload “Save snapshot”
• FileInput “Load snapshot”

2.6 Delta entre runs

But: sortir les variations entre snapshot chargé et run courant:

• New degraded
• Still degraded
• Resolved
• Severity up / down

Sorties:

• onglet UI “Delta”
• feuille Excel “Delta”

---

Phase 4 — Visualisation (Map + Corrélation) (priorité moyenne)

2.7 Map des sites dégradés

But: voir des clusters (zone / ville) et naviguer vers le drill-down.

Pré-requis:

• Latitude / Longitude disponibles (normalisation ou physical db).

Affichage:

• Plotly scatter_mapbox (style open-street-map) ou scatter_geo
• Couleur = status (ou degraded/persistent)
• Taille = criticité (weighted si dispo)

Interaction:

• click point => sélection site dans drill-down

2.8 KPI Correlation Explorer

But: RCA rapide sur un site/RAT.

• Matrice corrélation des KPI sélectionnés (Pearson/Spearman)
• fenêtre: recent / baseline / full filtered range
• sortie: heatmap Plotly (px.imshow)

---

3) RCA Hints (bonus mais très utile)

Objectif: rendre Top_Anomalies plus actionnable.

Ajouts colonnes:

• delta_pct
• sla_breached
• reason (texte)
• data_quality_flag

Ces colonnes peuvent être calculées:

• lors de la génération de Top_Anomalies (dans multi_rat.py),
• ou côté Panel lors du refresh (plus rapide à itérer).

---

4) Découpage technique (recommandé)

Pour éviter d’alourdir kpi_health_check_panel.py:

• process_kpi/kpi_health_check/snapshot.py

  • save/load snapshot + validation version
  • compute delta

• process_kpi/kpi_health_check/ops_queue.py

  • build ops queue df

• panel_app/kpi_health_check_maps.py

  • build map figure

• process_kpi/kpi_health_check/correlation.py

  • build correlation matrix

---

4.1) Qualité des données & garde-fous (à intégrer dès Sprint 1)

• Validation d’inputs:
  • dataset vide / pas de date_only / pas de site_code
  • aucun point dans la analysis_range
• Validation complaint list:
  • parsing robuste (csv/txt/xlsx déjà prévu)
  • normalisation des codes site (cast int + extraction regex si besoin)
• Fail-safe: si is_complaint_site n’existe pas, ne pas crasher (considérer False).

4.2) Performance / mémoire (à surveiller)

• Limiter le volume affiché dans les tables (ex: top N) quand nécessaire.
• Éviter les copies inutiles de DataFrames lors des refresh.
• Garder les calculs lourds dans process_kpi/* et l’UI comme orchestration.

4.3) Tests rapides (smoke tests) / DoD

Minimum avant de considérer une phase “done”:

• Charger un petit sample 2G/3G/LTE et exécuter Load + Run sans erreur.
• Vérifier:
  • export Excel principal
  • export complaint
  • double-click tables => drill-down
  • aucun crash si complaint list absente

---

5) Critères de réussite globaux

• Exploitation: obtenir une liste priorisée + top anomalies complaint en < 1 minute.
• Partage: export Excel avec onglets complaint + delta.
• Visualisation: map cliquable et corrélation sur drill-down.

---

6) Plan de livraison (sprints)

• Sprint 1: Complaint UI tab + Export complaint sheets
• Sprint 2: Ops Queue + Alert Pack
• Sprint 3: Snapshot + Delta
• Sprint 4: Map + Correlation explorer
• Sprint 5 (option): RCA hints (reason/tags)

---

7) Risques & mitigations

• Volumes importants (beaucoup de sites/KPI/jours):
  • mitigation: top-N dans certaines vues + pagination Tabulator + éviter les figures avec trop de traces.
• Coordonnées manquantes (pas de Lat/Lon):
  • mitigation: la map doit être optionnelle et afficher un message clair si données insuffisantes.
• Excel / automatisation utilisateur (noms d’onglets attendus):
  • mitigation: ajouter les nouveaux onglets sans renommer les existants.